COBOL Tutorial

COBOL ARGUMENT-NUMBER

ARGUMENT-NUMBER represents one of COBOL's most essential and sophisticated runtime parameter management mechanisms, serving as the primary interface for accessing command-line arguments, runtime parameters, and dynamic program configuration data that enables applications to receive external input, process startup parameters, and implement flexible program behavior based on execution context. Far more than a simple parameter counter, ARGUMENT-NUMBER embodies COBOL's comprehensive approach to runtime configuration by providing command-line argument enumeration, parameter sequence management, dynamic input processing capabilities, and sophisticated argument validation techniques that enable applications to implement flexible startup procedures, configurable processing modes, and comprehensive parameter-driven execution strategies while maintaining robust error handling, parameter validation, and enterprise-grade runtime configuration capabilities essential for modern mainframe applications requiring dynamic behavior and flexible operational parameters.

In enterprise computing environments, ARGUMENT-NUMBER serves as a critical foundation for dynamic program configuration implementation, enabling developers to create sophisticated parameter-driven applications that handle complex startup requirements, implement configurable processing modes, provide comprehensive runtime customization capabilities, and maintain high-performance argument processing functionality. Its capabilities extend far beyond simple parameter counting to encompass sophisticated argument enumeration strategies, parameter validation techniques, complex configuration management patterns, and integration with modern deployment paradigms that are essential for applications requiring comprehensive runtime configuration and enterprise-grade parameter management capabilities that support flexible operational modes and advanced configuration-driven processing requirements across multiple execution contexts and sophisticated deployment environments.

Understanding ARGUMENT-NUMBER

What is ARGUMENT-NUMBER?

ARGUMENT-NUMBER is a special COBOL intrinsic function that returns the total count of command-line arguments passed to a program when it was invoked. This function is essential for programs that need to process variable numbers of parameters, validate argument counts, and implement dynamic behavior based on the number of parameters provided at runtime. Unlike fixed parameter processing, ARGUMENT-NUMBER enables programs to adapt their behavior based on how many arguments were actually provided during program execution.

This capability is particularly valuable in batch processing environments, utility programs, and applications that need to handle varying operational modes. For example, a file processing utility might accept different numbers of parameters depending on whether it's performing simple copying, complex transformations, or multi-file operations. ARGUMENT-NUMBER allows the program to determine how many parameters were provided and adjust its processing logic accordingly.

Key Characteristics of ARGUMENT-NUMBER:

Runtime Parameter Counting: Returns the total number of command-line arguments
Dynamic Processing: Enables variable parameter handling and validation
Zero-Based or One-Based: Implementation may vary by COBOL compiler
Read-Only Access: Provides information about argument count, not modification
Execution Context: Reflects the actual invocation parameters

Basic ARGUMENT-NUMBER Usage

The basic usage of ARGUMENT-NUMBER involves calling the function to retrieve the count of command-line arguments and using this information to control program flow. The function typically returns a numeric value that can be tested, stored, and used in conditional logic to determine appropriate processing paths based on the number of parameters provided.

cobol

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
*> Basic ARGUMENT-NUMBER usage for parameter validation
IDENTIFICATION DIVISION.
PROGRAM-ID. ARGUMENT-DEMO.
 
DATA DIVISION.
WORKING-STORAGE SECTION.
01  WS-ARG-COUNT            PIC 9(3) VALUE ZERO.
01  WS-PROCESSING-MODE      PIC X(20) VALUE SPACES.
01  WS-ERROR-FLAG           PIC X VALUE 'N'.
 
PROCEDURE DIVISION.
MAIN-PROCESSING.
    *> Get the number of command-line arguments
    MOVE FUNCTION ARGUMENT-NUMBER TO WS-ARG-COUNT
    
    *> Validate argument count and determine processing mode
    EVALUATE WS-ARG-COUNT
        WHEN 0
            DISPLAY "Error: No arguments provided"
            DISPLAY "Usage: PROGRAM input-file [output-file] [options]"
            MOVE 'Y' TO WS-ERROR-FLAG
        WHEN 1
            MOVE "DISPLAY-MODE" TO WS-PROCESSING-MODE
            DISPLAY "Single argument mode: Display processing"
        WHEN 2
            MOVE "COPY-MODE" TO WS-PROCESSING-MODE
            DISPLAY "Two argument mode: File copy processing"
        WHEN 3
            MOVE "TRANSFORM-MODE" TO WS-PROCESSING-MODE
            DISPLAY "Three argument mode: File transformation"
        WHEN OTHER
            DISPLAY "Warning: " WS-ARG-COUNT " arguments provided"
            DISPLAY "Using advanced processing mode"
            MOVE "ADVANCED-MODE" TO WS-PROCESSING-MODE
    END-EVALUATE
    
    *> Continue processing based on mode
    IF WS-ERROR-FLAG = 'N'
        PERFORM PROCESS-ARGUMENTS
    END-IF
    
    GOBACK.
 
PROCESS-ARGUMENTS.
    DISPLAY "Processing mode: " WS-PROCESSING-MODE
    DISPLAY "Argument count: " WS-ARG-COUNT
    *> Additional processing logic here
    .

This example shows basic argument count validation and mode determination.

Notice how the program uses ARGUMENT-NUMBER to determine the appropriate processing mode based on how many parameters were provided. This approach allows a single program to handle multiple operational scenarios without requiring separate programs for each mode. The EVALUATE statement provides clear logic for handling different argument counts, including error conditions when no arguments are provided.

Advanced Parameter Processing

Advanced parameter processing combines ARGUMENT-NUMBER with ARGUMENT-VALUE to create sophisticated command-line interfaces. This approach enables programs to validate not only the number of arguments but also their content, format, and relationships. Such processing is essential for enterprise applications that need robust parameter validation and flexible operational modes.

Enterprise applications often require complex parameter validation, including checking for required parameters, optional flags, parameter dependencies, and format validation. ARGUMENT-NUMBER provides the foundation for this validation by enabling programs to iterate through all provided arguments systematically and apply appropriate validation rules based on position, content, and context.

cobol

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
*> Advanced parameter processing with validation
IDENTIFICATION DIVISION.
PROGRAM-ID. ADVANCED-ARGS.
 
DATA DIVISION.
WORKING-STORAGE SECTION.
01  WS-ARG-COUNT            PIC 9(3) VALUE ZERO.
01  WS-ARG-INDEX            PIC 9(3) VALUE ZERO.
01  WS-CURRENT-ARG          PIC X(100) VALUE SPACES.
01  WS-VALIDATION-STATUS    PIC X VALUE 'Y'.
 
01  WS-PROGRAM-OPTIONS.
    05  WS-INPUT-FILE       PIC X(50) VALUE SPACES.
    05  WS-OUTPUT-FILE      PIC X(50) VALUE SPACES.
    05  WS-VERBOSE-MODE     PIC X VALUE 'N'.
    05  WS-DEBUG-MODE       PIC X VALUE 'N'.
    05  WS-BACKUP-MODE      PIC X VALUE 'N'.
    05  WS-FORMAT-TYPE      PIC X(10) VALUE 'DEFAULT'.
 
01  WS-VALIDATION-COUNTERS.
    05  WS-FILE-COUNT       PIC 9 VALUE ZERO.
    05  WS-OPTION-COUNT     PIC 9 VALUE ZERO.
    05  WS-ERROR-COUNT      PIC 9 VALUE ZERO.
 
PROCEDURE DIVISION.
MAIN-PROCESSING.
    MOVE FUNCTION ARGUMENT-NUMBER TO WS-ARG-COUNT
    
    *> Validate minimum argument requirements
    IF WS-ARG-COUNT < 1
        DISPLAY "Error: At least one argument required"
        PERFORM DISPLAY-USAGE
        MOVE 'N' TO WS-VALIDATION-STATUS
    END-IF
    
    *> Process each argument systematically
    IF WS-VALIDATION-STATUS = 'Y'
        PERFORM VARYING WS-ARG-INDEX FROM 1 BY 1
            UNTIL WS-ARG-INDEX > WS-ARG-COUNT
            OR WS-VALIDATION-STATUS = 'N'
            
            MOVE FUNCTION ARGUMENT-VALUE(WS-ARG-INDEX) 
                TO WS-CURRENT-ARG
            PERFORM PROCESS-SINGLE-ARGUMENT
        END-PERFORM
    END-IF
    
    *> Final validation and processing
    IF WS-VALIDATION-STATUS = 'Y'
        PERFORM VALIDATE-ARGUMENT-COMBINATIONS
        IF WS-VALIDATION-STATUS = 'Y'
            PERFORM EXECUTE-PROCESSING
        END-IF
    END-IF
    
    GOBACK.
 
PROCESS-SINGLE-ARGUMENT.
    *> Check if argument is an option (starts with -)
    IF WS-CURRENT-ARG(1:1) = '-'
        PERFORM PROCESS-OPTION-ARGUMENT
    ELSE
        PERFORM PROCESS-FILE-ARGUMENT
    END-IF.
 
PROCESS-OPTION-ARGUMENT.
    ADD 1 TO WS-OPTION-COUNT
    
    EVALUATE WS-CURRENT-ARG(1:2)
        WHEN '-v'
            MOVE 'Y' TO WS-VERBOSE-MODE
            DISPLAY "Verbose mode enabled"
        WHEN '-d'
            MOVE 'Y' TO WS-DEBUG-MODE
            DISPLAY "Debug mode enabled"
        WHEN '-b'
            MOVE 'Y' TO WS-BACKUP-MODE
            DISPLAY "Backup mode enabled"
        WHEN OTHER
            *> Check for format specification
            IF WS-CURRENT-ARG(1:3) = '-f='
                MOVE WS-CURRENT-ARG(4:) TO WS-FORMAT-TYPE
                DISPLAY "Format type: " WS-FORMAT-TYPE
            ELSE
                DISPLAY "Warning: Unknown option " WS-CURRENT-ARG
                ADD 1 TO WS-ERROR-COUNT
            END-IF
    END-EVALUATE.
 
PROCESS-FILE-ARGUMENT.
    ADD 1 TO WS-FILE-COUNT
    
    EVALUATE WS-FILE-COUNT
        WHEN 1
            MOVE WS-CURRENT-ARG TO WS-INPUT-FILE
            DISPLAY "Input file: " WS-INPUT-FILE
        WHEN 2
            MOVE WS-CURRENT-ARG TO WS-OUTPUT-FILE
            DISPLAY "Output file: " WS-OUTPUT-FILE
        WHEN OTHER
            DISPLAY "Error: Too many file arguments"
            MOVE 'N' TO WS-VALIDATION-STATUS
    END-EVALUATE.
 
VALIDATE-ARGUMENT-COMBINATIONS.
    *> Ensure required files are specified
    IF WS-INPUT-FILE = SPACES
        DISPLAY "Error: Input file must be specified"
        MOVE 'N' TO WS-VALIDATION-STATUS
    END-IF
    
    *> Validate option combinations
    IF WS-DEBUG-MODE = 'Y' AND WS-VERBOSE-MODE = 'N'
        DISPLAY "Warning: Debug mode enabled without verbose mode"
    END-IF
    
    *> Check for conflicting options
    IF WS-BACKUP-MODE = 'Y' AND WS-OUTPUT-FILE = SPACES
        DISPLAY "Error: Backup mode requires output file"
        MOVE 'N' TO WS-VALIDATION-STATUS
    END-IF.
 
DISPLAY-USAGE.
    DISPLAY "Usage: PROGRAM input-file [output-file] [options]"
    DISPLAY "Options:"
    DISPLAY "  -v        Enable verbose mode"
    DISPLAY "  -d        Enable debug mode"
    DISPLAY "  -b        Enable backup mode"
    DISPLAY "  -f=TYPE   Specify format type"
    DISPLAY "Examples:"
    DISPLAY "  PROGRAM data.txt"
    DISPLAY "  PROGRAM input.txt output.txt -v -b"
    DISPLAY "  PROGRAM data.txt -f=XML -d".
 
EXECUTE-PROCESSING.
    DISPLAY "Starting processing with validated parameters:"
    DISPLAY "  Input file: " WS-INPUT-FILE
    IF WS-OUTPUT-FILE NOT = SPACES
        DISPLAY "  Output file: " WS-OUTPUT-FILE
    END-IF
    DISPLAY "  Verbose mode: " WS-VERBOSE-MODE
    DISPLAY "  Debug mode: " WS-DEBUG-MODE
    DISPLAY "  Backup mode: " WS-BACKUP-MODE
    DISPLAY "  Format type: " WS-FORMAT-TYPE
    *> Actual processing logic would go here
    .

This example demonstrates comprehensive parameter processing with validation and option handling.

Enterprise Batch Processing Example

In enterprise environments, ARGUMENT-NUMBER is frequently used in batch processing systems where programs need to handle varying operational requirements. This example demonstrates a comprehensive data processing utility that uses ARGUMENT-NUMBER to implement flexible processing modes, comprehensive validation, and enterprise-grade error handling.

cobol

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
*> Enterprise batch processing with ARGUMENT-NUMBER
IDENTIFICATION DIVISION.
PROGRAM-ID. ENTERPRISE-BATCH.
 
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
    SELECT CONFIG-FILE ASSIGN TO WS-CONFIG-FILENAME
        ORGANIZATION IS LINE SEQUENTIAL.
 
DATA DIVISION.
FILE SECTION.
FD  CONFIG-FILE.
01  CONFIG-RECORD           PIC X(100).
 
WORKING-STORAGE SECTION.
01  WS-ARG-COUNT            PIC 9(3) VALUE ZERO.
01  WS-CONFIG-FILENAME      PIC X(50) VALUE SPACES.
01  WS-PROCESSING-DATE      PIC X(8) VALUE SPACES.
01  WS-DEPARTMENT-CODE      PIC X(5) VALUE SPACES.
01  WS-REPORT-TYPE          PIC X(10) VALUE SPACES.
 
01  WS-BATCH-CONTROL.
    05  WS-JOB-ID           PIC X(10) VALUE SPACES.
    05  WS-STEP-NUMBER      PIC 9(3) VALUE ZERO.
    05  WS-RESTART-POINT    PIC X(20) VALUE SPACES.
    05  WS-PRIORITY-LEVEL   PIC 9 VALUE 5.
 
01  WS-PROCESSING-OPTIONS.
    05  WS-FULL-REFRESH     PIC X VALUE 'N'.
    05  WS-INCREMENTAL      PIC X VALUE 'N'.
    05  WS-VALIDATION-ONLY  PIC X VALUE 'N'.
    05  WS-PARALLEL-MODE    PIC X VALUE 'N'.
    05  WS-AUDIT-TRAIL      PIC X VALUE 'Y'.
 
01  WS-RUNTIME-PARAMETERS.
    05  WS-MAX-RECORDS      PIC 9(8) VALUE 999999.
    05  WS-TIMEOUT-MINUTES  PIC 9(3) VALUE 60.
    05  WS-RETRY-COUNT      PIC 9 VALUE 3.
    05  WS-CHECKPOINT-FREQ  PIC 9(4) VALUE 1000.
 
PROCEDURE DIVISION.
MAIN-BATCH-PROCESSING.
    PERFORM INITIALIZE-BATCH-ENVIRONMENT
    PERFORM PROCESS-COMMAND-ARGUMENTS
    PERFORM VALIDATE-BATCH-PARAMETERS
    PERFORM EXECUTE-BATCH-PROCESSING
    PERFORM CLEANUP-BATCH-ENVIRONMENT
    GOBACK.
 
PROCESS-COMMAND-ARGUMENTS.
    MOVE FUNCTION ARGUMENT-NUMBER TO WS-ARG-COUNT
    
    *> Enterprise batch programs require specific argument patterns
    EVALUATE WS-ARG-COUNT
        WHEN 0
            DISPLAY "BATCH001E: No arguments provided"
            PERFORM DISPLAY-ENTERPRISE-USAGE
            MOVE 12 TO RETURN-CODE
        WHEN 1
            *> Single argument: configuration file only
            MOVE FUNCTION ARGUMENT-VALUE(1) TO WS-CONFIG-FILENAME
            PERFORM LOAD-CONFIGURATION-FILE
        WHEN 2
            *> Two arguments: config file + processing date
            MOVE FUNCTION ARGUMENT-VALUE(1) TO WS-CONFIG-FILENAME
            MOVE FUNCTION ARGUMENT-VALUE(2) TO WS-PROCESSING-DATE
            PERFORM VALIDATE-PROCESSING-DATE
        WHEN 3
            *> Three arguments: config + date + department
            MOVE FUNCTION ARGUMENT-VALUE(1) TO WS-CONFIG-FILENAME
            MOVE FUNCTION ARGUMENT-VALUE(2) TO WS-PROCESSING-DATE
            MOVE FUNCTION ARGUMENT-VALUE(3) TO WS-DEPARTMENT-CODE
            PERFORM VALIDATE-DEPARTMENT-CODE
        WHEN 4
            *> Four arguments: config + date + dept + report type
            MOVE FUNCTION ARGUMENT-VALUE(1) TO WS-CONFIG-FILENAME
            MOVE FUNCTION ARGUMENT-VALUE(2) TO WS-PROCESSING-DATE
            MOVE FUNCTION ARGUMENT-VALUE(3) TO WS-DEPARTMENT-CODE
            MOVE FUNCTION ARGUMENT-VALUE(4) TO WS-REPORT-TYPE
            PERFORM VALIDATE-REPORT-TYPE
        WHEN OTHER
            *> Five or more arguments: advanced processing mode
            PERFORM PROCESS-ADVANCED-ARGUMENTS
    END-EVALUATE.
 
PROCESS-ADVANCED-ARGUMENTS.
    *> Handle complex argument patterns for enterprise processing
    MOVE FUNCTION ARGUMENT-VALUE(1) TO WS-CONFIG-FILENAME
    MOVE FUNCTION ARGUMENT-VALUE(2) TO WS-PROCESSING-DATE
    MOVE FUNCTION ARGUMENT-VALUE(3) TO WS-DEPARTMENT-CODE
    MOVE FUNCTION ARGUMENT-VALUE(4) TO WS-REPORT-TYPE
    
    *> Process additional arguments as job control parameters
    IF WS-ARG-COUNT >= 5
        MOVE FUNCTION ARGUMENT-VALUE(5) TO WS-JOB-ID
    END-IF
    
    IF WS-ARG-COUNT >= 6
        MOVE FUNCTION ARGUMENT-VALUE(6) TO WS-STEP-NUMBER
    END-IF
    
    IF WS-ARG-COUNT >= 7
        MOVE FUNCTION ARGUMENT-VALUE(7) TO WS-RESTART-POINT
    END-IF
    
    *> Process processing options from remaining arguments
    PERFORM VARYING WS-ARG-INDEX FROM 8 BY 1
        UNTIL WS-ARG-INDEX > WS-ARG-COUNT
        MOVE FUNCTION ARGUMENT-VALUE(WS-ARG-INDEX) TO WS-CURRENT-ARG
        PERFORM PROCESS-PROCESSING-OPTION
    END-PERFORM.
 
DISPLAY-ENTERPRISE-USAGE.
    DISPLAY "BATCH001I: Enterprise Batch Processing Utility"
    DISPLAY "Usage patterns:"
    DISPLAY "  1. CONFIG-FILE"
    DISPLAY "  2. CONFIG-FILE PROCESSING-DATE"
    DISPLAY "  3. CONFIG-FILE PROCESSING-DATE DEPT-CODE"
    DISPLAY "  4. CONFIG-FILE PROCESSING-DATE DEPT-CODE REPORT-TYPE"
    DISPLAY "  5. CONFIG-FILE PROCESSING-DATE DEPT-CODE REPORT-TYPE"
    DISPLAY "     JOB-ID [STEP-NUM] [RESTART-POINT] [OPTIONS...]"
    DISPLAY "Options:"
    DISPLAY "  FULL-REFRESH    - Complete data refresh"
    DISPLAY "  INCREMENTAL     - Process changes only"
    DISPLAY "  VALIDATION-ONLY - Validate without processing"
    DISPLAY "  PARALLEL-MODE   - Enable parallel processing"
    DISPLAY "  NO-AUDIT        - Disable audit trail"
    DISPLAY "Examples:"
    DISPLAY "  BATCH-PROG CONFIG.TXT"
    DISPLAY "  BATCH-PROG CONFIG.TXT 20240315"
    DISPLAY "  BATCH-PROG CONFIG.TXT 20240315 SALES MONTHLY"
    DISPLAY "  BATCH-PROG CONFIG.TXT 20240315 SALES MONTHLY"
    DISPLAY "             JOB001 001 CHECKPOINT-1 PARALLEL-MODE".

This enterprise example shows sophisticated argument processing for batch systems.

Best Practices and Common Pitfalls

Best Practices

Always Validate Argument Count: Check ARGUMENT-NUMBER before accessing individual arguments to prevent runtime errors
Provide Clear Usage Information: Display comprehensive usage instructions when argument validation fails
Implement Flexible Processing Modes: Use argument count to determine appropriate processing strategies
Handle Edge Cases: Account for zero arguments, excessive arguments, and invalid combinations
Use Consistent Error Codes: Implement standardized return codes for different error conditions
Document Argument Patterns: Clearly document expected argument sequences and optional parameters
Validate Argument Relationships: Check for dependencies and conflicts between different arguments

Common Pitfalls

Assuming Argument Availability: Accessing ARGUMENT-VALUE without checking ARGUMENT-NUMBER first
Ignoring Zero Arguments: Not handling the case where no command-line arguments are provided
Inconsistent Indexing: Confusion between zero-based and one-based argument indexing
Missing Validation: Failing to validate argument content and format after counting
Poor Error Messages: Providing unclear or unhelpful error messages for invalid arguments
Hardcoded Limits: Using fixed argument counts instead of flexible processing logic
No Usage Documentation: Failing to provide clear usage instructions for program invocation

Performance Considerations

ARGUMENT-NUMBER is typically a lightweight function call that returns a cached value, making it suitable for frequent use within argument processing loops. However, consider storing the result in a working storage variable if you need to reference it multiple times throughout your program.

For programs that process large numbers of arguments, consider implementing efficient validation strategies that minimize redundant checks and provide early termination for invalid argument patterns. This approach improves both performance and user experience by providing immediate feedback on argument errors.

Related COBOL Features

ARGUMENT-NUMBER works closely with ARGUMENT-VALUE for complete command-line processing, ACCEPT FROM COMMAND-LINE for alternative parameter access, and DISPLAY statements for user feedback and error reporting.

Understanding these related features enables comprehensive command-line interface implementation and robust parameter processing in enterprise COBOL applications.