HP 3000 Manuals HP 3000 Manuals
CALL Statement In ANSI COBOL, you can use the CALL statement to transfer control from one object program to another within the same run unit.[REV BEG] An HP extension to the 1985 ANSI COBOL standard[REV END] adds the ability to invoke operating system intrinsics from within a given object program. Syntax[REV BEG] An HP extension to the 1985 ANSI COBOL standard[REV END] adds the keyword INTRINSIC to the following formats to specify that an intrinsic, not a program, is being called. Also added is the capability to pass a data item by value. These can only be used when calling non-COBOL programs. The last format of the CALL statement is the GIVING identifier-4 phrase. This phrase allows you to name an identifier that holds the result of a call to a typed procedure.Parameters identifier-1 names an alphanumeric data item whose value is a program name. Refer to "CALL Identifier" (below) for a description of conditions that may occur when using this operation. literal-1 nonnumeric literal that either names an operating system intrinsic, or names a program. If an intrinsic is named by literal-1, the keyword, INTRINSIC, must precede it. \\ represents a null value passed as a parameter to an intrinsic[REV BEG] or to a Pascal procedure that includes OPTION DEFAULT_PARMS or EXTENSIBLE.[REV END] The compiler assumes a one-word parameter when the INTRINSIC option is not specified.[REV BEG] @ identifier-2 @ is ignored; this is provided for compatibility with HP COBOLII/V.[REV END][REV BEG] identifier-2 cannot be a function-identifier.[REV END] identifier-2, the name of any data item in the calling program, or a file named in an FD level entry in the FILE SECTION of your program. identifier-2 must be described in the FILE, WORKING-STORAGE, or LINKAGE SECTIONs of your program. When this value is passed to another program, it is passed by reference. If this parameter names a file, the called program must not be a COBOL program[REV BEG] unless the BY CONTENT phrase is used.[REV END] [REV BEG] identifier-2 cannot be a function-identifier.[REV END] \identifier-2\, and used to indicate that the literals or data \literal-2\, items represented by identifiers enclosed by the back slashes are to be passed by value to the called program or intrinsic. This may only be used when the called program is not a COBOL program. If an identifier is used in this way, it must represent a numeric[REV BEG] data item of up to 18 digits.[REV END] [REV BEG] identifier-2 cannot be a function-identifier.[REV END][REV BEG] identifier-4 the name of a binary data item in the calling program. It is used in calls to non-COBOL programs and in calls to COBOL programs that return a value in the RETURN-CODE special register (see the section "GIVING Phrase When Calling COBOL Subprograms" later in this chapter for details.)[REV END] [REV BEG] identifier-4 cannot be a function-identifier.[REV END] imperative-statement-1 one or more imperative statements. Description A CALL statement may appear anywhere within a segmented program. The compiler provides all controls necessary to ensure that the proper logic flow is maintained. When a CALL statement to a subprogram appears in a section with a segment number greater than or equal to 50, and when control is returned to this segment by the EXIT PROGRAM statement in the called subprogram, this segment is in the same state as when it issued the CALL statement. Example The ANSI COBOL'85 standard contains several rules that govern the scope of CALL statements for nested, concatenated and mixed programs. The following example illustrates several cases. In the example, only the PROGRAM-ID, CALL, and END PROGRAM are shown for the COBOL program. For clarity, the lines are indented to illustrate the scope. However, in practice, both PROGRAM-ID and END PROGRAM must start in margin A, and a CALL statement should start in margin B. Line Program Structure Scope 1 PROGRAM-ID. A. Start of program A. 2 : 3 PROGRAM-ID. C COMMON. Start of nested program C. 4 : Program C is contained within program A. 5 END PROGRAM C. End of nested program C. 6 END PROGRAM A. End of program A. 7 8 PROGRAM-ID. F. Start of program F. 9 : 10 CALL "A". Calls nested program A in line 11. 11 PROGRAM-ID. A. Start of nested program A. 12 : Program A is contained within program F. 13 END PROGRAM A. End of nested program A. 14 15 PROGRAM-ID. B. Start of nested program B. 16 : Program B is contained within program F. 17 CALL "A". Calls program A in line 1. 18 END PROGRAM B. End of nested program B. 19 END PROGRAM F. End of program F. Calling Intrinsics The INTRINSIC phrase is used to indicate that the CALL statement in which it appears is calling an operating system intrinsic rather than a subprogram. When the INTRINSIC phrase is used, literal-1 must be used and must name an operating system intrinsic. The USING phrase specifies the various parameters to be passed to the intrinsic. When the intrinsic is a "typed procedure", the GIVING phrase specifies the parameter to be returned by the intrinsic. As with subprograms, the parameters passed to intrinsics are specified by position. If a parameter of an intrinsic is optional, and you do not want to pass a value for that parameter, you must specify two consecutive back slashes (\\) in the position within the USING phrase of the CALL statement that corresponds to that parameter's position within the intrinsic. Unlike subprograms, if an intrinsic expects a parameter to be passed by value rather than by reference, it is unnecessary to enclose the literal or identifier with backslashes. The intrinsic automatically assumes that the parameter is being passed by value. The following special relation operator can be used after a call to an intrinsic to check the condition code returned by an intrinsic:This relation condition is described under "Relation Conditions" in Chapter 8 . For information on the condition codes and the types, number, and position of parameters required to call a specific intrinsic, refer to the MPE Intrinsics Reference Manual and to "System Dependencies" in Appendix H . Example. The following shows some calls to intrinsics: SPECIAL-NAMES. CONDITION-CODE IS C-C. : WORKING-STORAGE SECTION. 01 SHOWME. 02 MPE-COMMAND PIC X(07) VALUE "SHOWJOB". 02 CARRIAGE-RETURN PIC X VALUE %15. 01 ERR PIC S9999 USAGE IS COMP VALUE ZERO. 01 CATCHPARM PIC S9999 USAGE IS COMP VALUE ZERO. 01 REPLY PIC X(03) VALUE SPACES. : PROCEDURE DIVISION. : CALL INTRINSIC "COMMAND" USING SHOWME ERR CATCHPARM. IF C-C NOT = 0 THEN DISPLAY "COMMAND FAILED" STOP RUN. MOVE SPACES TO REPLY. DISPLAY "DO YOU WISH TO COMMUNICATE WITH ANYONE?" ACCEPT REPLY. IF REPLY = "YES" PERFORM BREAK-FOR-COMM. : BREAK-FOR-COMM. DISPLAY "TYPE RESUME WHEN READY TO RESUME PROGRAM". CALL INTRINSIC "CAUSEBREAK". : The first intrinsic call above uses the COMMAND intrinsic to issue the operating system command SHOWJOB. This allows you to see who is currently logged on to your system. The second call to an intrinsic is the programmatic equivalent to pressing the BREAK key, thus suspending your program. The intrinsics used in the above manner could allow you to see who is using the system and to ask them, for example, to release a file from their group to allow your program to access it. When CALL INTRINSIC is used for intrinsics in a system file: 1. The special symbols "@" and "\" are optional. 2. Data conversions for parameters passed by value are performed automatically. [REV BEG] Execution-Time Loading [REV END] When you use the identifier-1 form of the CALL statement, the value of identifier-1 determines which subprogram is called. When the program is executed, an attempt is made to load the subprogram. If the load fails, an exception condition occurs. For more information, see "System Dependencies" in Appendix H . [REV BEG] If the ON EXCEPTION or ON OVERFLOW phrase is specified,[REV END] control is passed to the imperative statement of that phrase. If no ON EXCEPTION or ON OVERFLOW phrase is specified and the CALL statement causes an exception condition, the entire run unit is aborted. The identifier-1 form of CALL may be useful for calling a procedure used optionally and infrequently by your program or for a procedure whose name is not known at load time.
CAUTION Indiscriminate use of ON EXCEPTION or ON OVERFLOW may adversely affect the performance level of an active system or a system where multiple users are running the same program utilizing this capability. Do not use these phrases when using a literal to name the program to be called[REV BEG] because the call is treated the same as a CALL identifier.[REV END]
Pseudo-Intrinsics The following pseudo-intrinsics are an HP extension to the ANSI COBOL standard.
CAUTION Pseudo-intrinsics are highly machine-dependent and should not be used in programs that may be run on different machines and architectures now or in the future.
.LOC. Pseudo-Intrinsic. The .LOC. pseudo-intrinsic allows you to call several useful operating system intrinsics, such as GENMESSAGE, CREATEPROCESS, MYCOMMAND, and other intrinsics that require identifiers to contain addresses. Input to this intrinsic is the name of an identifier for which an address is desired. The address of this identifier is returned in the GIVING identifier. Refer to "System Dependencies" in Appendix H for the correct size of the GIVING identifier. .LEN. Pseudo-Intrinsic. The .LEN. pseudo-intrinsic can be used to calculate the length of items, groups or tables. .LEN. returns the length in bytes of its parameter, or the current length of a table whose length has an OCCURS DEPENDING ON clause. Example. One important use of .LEN. is to calculate the length of records passed to intrinsics like VPLUS. For example: 01 V-REC. 05 FIELD-1 PIC XX. 05 FIELD-2 PIC X(10). : 77 V-REC-LEN PIC S9(4) COMP. : CALL INTRINSIC ".LEN." USING V-REC GIVING V-REC-LEN. CALL INTRINSIC "VPUTBUFFER" USING COMAREA V-REC V-REC-LEN. The above code sequence has the advantage that the length of the record V-REC is not hard coded, and additional fields can be added to V-REC without having to change the PROCEDURE DIVISION or a variable that contains the length. Also, with the HP COBOL II compiler doing the calculation, there are no mistakes in adding up the individual field lengths. [REV BEG] To conform to the 1985 ANSI COBOL standard, you can use the LENGTH COBOL function instead of .LEN. (see Chapter 10 for details).[REV END] USING Phrase (COBOL Subprograms) The USING phrase specified in a CALL statement to another program makes data and files of the calling program available to the called program. If a CALL statement containing the USING phrase calls a COBOL program, then the called COBOL program must contain a USING phrase in its PROCEDURE DIVISION header (or in the ENTRY statement, if a secondary entry point name is used by the CALL statement). The USING phrase of the called program must contain as many operands as does the USING phrase of the calling program. The USING option makes data items (or FD file names) defined in the calling program available to a called subprogram. However, file names cannot be passed to a COBOL subprogram unless BY CONTENT is specified. Note that the limit of data items in the USING phrase also applies to the number of 01/77 level entries, excluding redefinitions, defined in the LINKAGE SECTION of the called subprograms. Refer to "System Dependencies" in Appendix H for specifics on limitations. The order of appearance of names of data items in the USING phrase is very important (refer to "Reference to Common Data through Parameter Passing" at the beginning of this chapter). To restate briefly, data is passed from the calling program to the called program on a positional basis, rather than by name. Therefore, the third name in a USING phrase of a calling program corresponds to the third name in the USING phrase of the called COBOL program. Both the BY CONTENT and BY REFERENCE phrases cause the parameters that follow them to be passed by content or reference until another BY CONTENT or BY REFERENCE phrase is encountered. If neither the BY CONTENT nor the BY REFERENCE phrase is specified prior to the first parameter, BY REFERENCE is assumed.
NOTE ANSI COBOL'74 parameters are always passed by reference.
Index names in the calling and called programs always refer to different indices. To pass an index value from a calling program to a called program, you must first move the index value associated with an index name to a data item that appears in the USING phrase of the calling program. The corresponding data item in the called program can then be used to set an equivalent index name to this value. BY REFERENCE Phrase. The BY REFERENCE phrase is a feature of the 1985 ANSI COBOL standard. If the BY REFERENCE phrase is either specified or implied for a parameter, the object program operates as if the corresponding data item in the called program occupies the same storage area as the data item in the calling program. The description of the data item in the called program must describe the same number of character positions as the corresponding data item in the calling program. BY CONTENT Phrase. The BY CONTENT phrase is a feature of the 1985 ANSI COBOL standard. If the BY CONTENT phrase is specified or implied for a parameter, the called program cannot change the value of this parameter as referenced in the CALL statement's USING phrase. However, the called program may change the value of the data item referenced by the corresponding data name in the called program's division header. That is, if the called program changes the value, the calling program never sees the change. CALL "SUBP" USING BY CONTENT PARM1 PARM2 BY REFERENCE PARM3 BY CONTENT PARM4
NOTE Do not use the BY CONTENT phrase when calling non-COBOL subprograms that contain value parameters. BY CONTENT is not the same as BY VALUE.
USING Phrase (Non-COBOL Subprograms) This positional correspondence extends to non-COBOL called programs. Thus, for example, if the called program is a Pascal program, then the names in the parameter list of the procedure declaration in that program are identified with those data items whose names appear in the corresponding position of the USING phrase in the calling program. As stated above in the description of identifier-2, identifier-3, and so forth, these identifiers may name files to be passed to a called[REV BEG] program. Furthermore, although you can[REV END] enclose such a file identifier between back slashes (which are ignored), preceding it with an @ sign results in an error. If the file name from the FD is passed, the file number of that file is passed by value. If the subprogram is an SPL procedure, the procedure parameter corresponding to the file name must be declared as type INTEGER or LOGICAL and it must be specified as a value parameter. The file must be opened in the calling program. To pass a data item by value, you must enclose the associated identifier in back slashes. If the value passed is a literal, the back slashes are optional. Passing a data item by value leaves the data item in the calling program unchanged following execution of the called program. [REV BEG] If an identifier is not passed by value (that is, is not enclosed in back slashes), it is passed as a byte pointer (that is, by reference). Thus, the data in the calling program[REV END] can be altered by the called program if it is passed in this manner. In calls to COBOL programs, this is the standard method of referencing common data. Two consecutive back slashes (\\) may be specified in a USING phrase of a CALL statement if the called program is[REV BEG] a Pascal procedure with OPTION DEFAULT_PARMS or EXTENSIBLE.[REV END] Using two consecutive back slashes indicates that a parameter is not being sent and should not be expected. Whenever an OPTION VARIABLE SPL procedure is called, an additional parameter must be added to the end of the USING parameter list. This parameter is called a "bit mask" and is used to tell the SPL procedure which parameters are being passed; each bit represents a parameter. It must be a numeric data item and represents the value derived from the bit mask. The bit mask is one or two 16-bit binary words, where a "0" represents a missing parameter, and a "1" represents an existing parameter (allows up to 32 parameters to be passed). Parameters are matched, starting from the right, in both the bit mask and the USING list, excluding the value in the USING list used for the bit mask parameter. For example, [REV BEG] CALL "SPLPROC" USING \TESTER\ \\ @RESULT \ERROR\ \%13\ [REV END][REV BEG] The bit mask in this case is 0000000000001011, which is represented by the octal value \%13\, showing that the fourth, third, and first parameters are[REV END] being passed, while the second parameter is not being passed. The bit mask is generated automatically by the compiler if you specify the INTRINSIC option. [REV BEG] GIVING Phrase When Calling COBOL Subprograms As an HP extension to the ANSI COBOL standard, you can return a value from a COBOL subprogram using the RETURN-CODE special register in the subprogram and the GIVING phrase in the calling program. The data item in the GIVING phrase must be defined as PIC S9(9) BINARY. If it is not, a type checking error may occur at link time. The value returned is the value placed into the RETURN-CODE special register by the called program. If a value is not placed into RETURN-CODE by the called program, or if RETURN-CODE is a user-defined data item in the called program, the GIVING item will contain uninitialized data. RETURN-CODE Special Register. RETURN-CODE is a predefined data name in the PROCEDURE DIVISION of a subprogram. It can be used wherever an elementary data item can be used and is predefined as PIC S9(9) BINARY. The RETURN-CODE special register must be set before executing an EXIT PROGRAM or GOBACK statement in the called program. The value in RETURN-CODE is made available to the calling program in the GIVING phrase of the CALL statement. If the program already contains a data item named RETURN-CODE, it takes precedence over the special register and you cannot access the special register. To access the special register, you must change your data item to something else.[REV END] [REV BEG] Example. The following example shows a main program and a subprogram with a secondary entry point. The main program calls the subprogram twice and displays the value returned in the GIVING phrase. Notice that the special register RETURN-CODE is not defined anywhere in the DATA DIVISION of the subprogram.[REV END] IDENTIFICATION DIVISION. PROGRAM-ID. RETURN-CODE-TEST. DATA DIVISION. WORKING-STORAGE SECTION. 01 BUF PIC S9(9) BINARY VALUE 99. 01 RESULT PIC S9(9) BINARY VALUE -99. PROCEDURE DIVISION. START-IT. CALL "SUB-MAIN-ENTRY" USING BUF GIVING RESULT. DISPLAY RESULT. CALL "SECOND-ENTRY" GIVING RESULT. DISPLAY RESULT. END PROGRAM RETURN-CODE-TEST. $CONTROL DYNAMIC IDENTIFICATION DIVISION. PROGRAM-ID. SUB-MAIN-ENTRY. DATA DIVISION. LINKAGE SECTION. 01 BUF PIC S9(9) BINARY VALUE 99. PROCEDURE DIVISION USING BUF. PARA-01. ADD 1 TO BUF GIVING RETURN-CODE. EXIT PROGRAM. PARA-02. ENTRY "SECOND-ENTRY". MOVE -5000 TO RETURN-CODE. When this program runs it displays the following: [REV BEG] +000000100 -000005000 [REV END] GIVING Phrase When Calling Non-COBOL Subprograms The GIVING phrase also allows you to call non-COBOL typed procedures. [REV BEG] A typed procedure (for example, a Pascal function declaration) must always return a value when it completes execution. In HP COBOL II, this is assumed to be a 2-, 4-, or 8-byte binary value of up to eighteen digits.[REV END] The purpose of the GIVING phrase is to provide for this returned value. Since identifier-4 is used to hold the value returned by a typed procedure, its length must be sufficient to accommodate the value returned. Use of the keyword INTRINSIC allows the compiler to check the procedure information within the system file and adjust the generated code to correctly prepare and clean up the stack prior to and following the execution of the CALL statement. [REV BEG] [REV END]
![[]](../../pic3k/M011820/FFN1233c50.gif)
![[]](../../pic3k/M011820/FFN1243c50.gif)
![[]](../../pic3k/M011820/FFN1253c50.gif)