CBL_GET_PROGRAM_INFO

Returns information for a named program, or a program in the current call stack.
Restriction: Functions 8 and 10 of this routine (return number of arguments) are supported for native COBOL only.

Syntax:

call "CBL_GET_PROGRAM_INFO" using by value function
                            by reference   param-block
                            by reference   return-buf
                            by reference   return-buf-len
                            returning      status-code

Parameters

function
Call prototype (see Key): cblt-x4-comp5
Picture: pic x(4) comp-5.
param-block
Group predefined as cblt-prog-info-params containing
 01 cblt-prog-info-params   typedef.
   03 cblte-gpi-size        cblt-x4-comp5.   *> pic x(4) comp-5.
   03 cblte-gpi-flags       cblt-x4-comp5.   *> pic x(4) comp-5.
   03 cblte-gpi-handle      cblt-pointer.    *> usage pointer.
   03 cblte-gpi-prog-id     cblt-pointer.    *> usage pointer.
   03 cblte-gpi-attrs       cblt-x4-comp5.   *> pic x(4) comp-5.
return-buf
Call prototype (see Key): cblt-prog-info-arg-info
Picture: pic x(n).
return-buf-len
Call prototype (see Key): cblt-x4-comp5
Picture: pic x(4) comp-5.
status-code
See Library Routines - Key.

On Entry:

function
Specifies the function to be performed:
0
Note: This function is supported for COBOL programs only.
Return status information for the current program. If you want to retrieve further information on this program, then bit 0 of the cblte-gpi-flags parameter must be set to indicate that this function should return cblte-gpi-handle, which will be used as an input to function 2 through 8. The initial program associated with cblte-gpi-handle is the current program.

When other functions that use cblte-gpi-handle have completed, you must use CBL_GET_PROGRAM_INFO again, with function set to 3, to deallocate the handle.

1 Return status information for named program. If you want to retrieve further information on this program, then bit 0 of the cblte-gpi-flags parameter must be set to indicate that this function should return cblte-gpi-handle, which will be used as an input to function 2 through 8. The initial program associated with cblte-gpi-handle is the named program.

When other functions that use cblte-gpi-handle have completed, you must use CBL_GET_PROGRAM_INFO again, with function set to 3, to deallocate the handle.

2
Note: This function is supported for COBOL programs only.
Return status information for the program that called the program currently associated with cblte-gpi-handle. This function requires that cblte-gpi-handle has been set up using functions 0 or 1. The program associated with cblte-gpi-handle is updated to the calling program.

When other functions that use cblte-gpi-handle have completed, you must use CBL_GET_PROGRAM_INFO again, with function set to 3, to deallocate the handle.

3 Close a previously created cblte-gpi-handle. This function requires a valid cblte-gpi-handle to have been created using function 0 or 1. A call with this function must be made when cblte-gpi-handle is finished with.
4 Find the first entry point of the program currently associated with cblte-gpi-handle. cblte-gpi-handle must have been set up using function 0 or 1. Once a call with this function has been made, you can repeatedly use this routine with function set to 5 to retrieve all remaining entry points in the program. Once all of the required entry points have been returned, you can use this routine with function set to 6 to terminate the entry-point search.
5 Find the next entry point of the program currently associated with cblte-gpi-handle. This function requires a valid cblte-gpi-handle to have been set up using function 0 or 1, and for function 4 to have been used to initiate the find first/next entry-point sequence.
6 Terminate the entry-point search. It requires a valid cblte-gpi-handle to have been set up using function 0 or 1, and for function 4 to have been called to initiate the find first/next entry-point sequence.
7 Return the full program-name of the program currently associated with cblte-gpi-handle. This function requires a valid cblte-gpi-handle to have been set up using function 0 or 1.
8
Note: This function is supported for native COBOL programs only.
Return the number of arguments the program currently associated with cblte-gpi-handle was called with. This information can only be returned if the program is on the current call stack.
9 Reserved.
10 Return the path and program name, or the program name only for the program currently associated with cblte-gpi-handle. This function depends on whether bit 5 is set in cblte-gpi-flags.
cblte-gpi-size
The size of the parameter block including this field. This should be set to a value of 20 on 32-bit systems, or 28 on 64-bit systems.
cblte-gpi-flags
A 32-bit word indicating what information is to be returned:
Bit 0
Determines whether functions 0 and 1 return cblte-gpi-handle. For all other functions, this bit is ignored.
0 Do not return cblte-gpi-handle (if function is set to 0 or 1)
1 Return cblte-gpi-handle (if function is set to 0 or 1)
Bit 1
Determines whether functions 0 and 2 should return the program's basename in name-buf as part of the program status information.
0 Do not return basename of program (if function is set to 0 or 2)
1 Return basename of program in name-buf (if function is set to 0 or 2)
Bit 2
Determines whether basenames and full program names that are input or returned in name-buf should be in null-terminated or space- terminated format.
0 All input and output names are space-terminated
1 All input and output names are null-terminated.
Bit 3
Determines whether functions 0, 1 and 2 should return the program's attributes in cblte-gpi-attr.
0 Do not return program attributes in cblte-gpi-attr.
1 Return program attributes in cblte-gpi-attr.
Bit 4
Determines whether function 2 should return information for all programs.
0 Do not return program information.
1 Return program information.
Bit 5
Determines whether function 10 should return the full path to the loaded module associated with cblte-gpi-handle.
0 Return full path.
1 Return program name only.
Bits 6-31
Reserved for future use - must be set to 0.
cblte-gpi-handle
A handle created by function 0 or 1.
(Must be specified for functions 2-10.)
return-buf
If function is set to:
0 The basename of the program for which information is required.
8 A group predefined as
01 RETURN-BUF.
     05 cblte-gpiai-size        pic x(4) comp-5 value zeroes.
     05 cblte-gpiai-argc        pic x(4) comp-5 value zeroes.
     05 cblte-gpiai-reserved1   pointer value null.
     05 cblte-gpiai-reserved2   pointer value null.

cblte-gpiai-size must be set to either 16 on 32-bit systems or 24 on 64-bit systems.

return-buf-len
The length of return-buf. If this is too small for the information being returned, the routine fails.

On Exit:

cblte-gpi-handle
The handle returned by functions 0 and 1, which must be used for all other functions.
cblte-gpi-prog-id
Unique identifier for the program currently associated with cblte-gpi-handle.
cblte-gpi-attr
Attributes of the program currently associated with cblte-gpi-handle.
Bit 0
0 Program not compiled using AMODE"24" Compiler directive.
1 Program compiled using the AMODE"24" Compiler directive .
Bit 1
0 Program not compiled using AMODE"31" Compiler directive.
1 Program compiled using the AMODE"31" Compiler directive .
Bit 2
0 Program compiled using the CHARSET(ASCII) Compiler directive.
1 Program compiled using the CHARSET(EBCDIC) Compiler directive.
Bit 3
Note: This bit is only applicable to COBOL programs.
0 Program not compiled using the ANS85 Compiler directive.
1 Program compiled using the ANS85 Compiler directive.
Bit 4
Note: This bit is only applicable to COBOL programs.
0 Program not compiled using the VSC2 Compiler directive.
1 Program compiled using the VSC2 Compiler directive (this Compiler directive is supported in native code only).
Bit 5
Note: This bit is only applicable to COBOL programs.
0 Program not compiled using the OSVS Compiler directive.
1 Program compiled using the OSVS Compiler directive (this Compiler directive is supported in native code only).
Bit 6
Note: This bit is only applicable to COBOL programs.
0 Program not compiled using the DATA"24" Compiler directive.
1 Program compiled using the DATA"24" Compiler directive.
Bit 7
Note: This bit is only applicable to COBOL programs.
0 Program not compiled using the DATA-CONTEXT Compiler directive.
1 Program compiled using the DATA-CONTEXT Compiler directive.
Bits 8-10
000 COBOL or unknown language.
001 PL/I.
010 to 111 Reserved.
Bit 11
Note: This bit is only applicable to PL/I programs.
0 Little-endian.
1 Big-endian.
Bits 12-22
Reserved for future use - must be set to 0.
Bit 23
Note: This bit is only applicable to COBOL programs.
0 Program not compiled using the AMODE"64" Compiler directive.
1 Program compiled using the AMODE"64" Compiler directive.
Bit 24
Note: This bit is only applicable to COBOL programs.
0 Program not compiled using the DATA"31" Compiler directive.
1 Program compiled using the DATA"31" Compiler directive.
Bit 25
Note: This bit is only applicable to COBOL programs.
0 Program is not an application controller.
1 Program is an application controller.
Bit 26
Note: This bit is only applicable to COBOL programs.
0 Program is not a system program.
1 Program is a system program.
Bit 27
Note: This bit is only applicable to COBOL programs.
0 Program is not a .390 assembler program.
1 Program is a .390 assembler program.
Bit 28
Note: This bit is only applicable to COBOL programs.
0 Program is not a member of a subsystem.
1 Program is a member of a subsystem.
Bit 29
Note: This bit is only applicable to COBOL programs.
0 Program exists in current call stack.
1 Program does not exist in current call stack.
Bit 30
Note: This bit is only applicable to COBOL programs.
0 Program is not canceled.
1 Program is canceled.
Bit 31
0 Program is COBOL.
1 Program is non-COBOL.
return-buf
If function was set to:
0, 2 The basename that was requested.
4, 5 The entry point name that was requested.
7 The full program name that was requested.
8 The call parameter information that was requested, where cblte-gpiai-argc contains the number of arguments the program was called with.

cblte-gpiai-reserved1 and cblte-gpiai-reserved2 remain set to NULL.

10 The path and program name, or the program name only for the program currently associated with cblte-gpi-handle.
return-buf-len
Length of the name returned in name-buf, or required buffer length if the status-code is 1013.
status-code
Status of operation:
0 Success.
500 End of information (returned by function 2 when there is no caller of the currently associated program, or by function 5 when no more entry points exist).
1000 Memory allocation error.
1001 Invalid cblte-gpi-handle input.
1006 Invalid operation on handle (returned by function 8 if the program associated with cblte-gpi-handle is not on the call stack).
1009 Invalid parameter.
1011 Program or entry name not found.
1013 Buffer too small for information to be returned.
Note: For an example of the equivalent PL/I declarations, assignments and call format, see the PL/I example topic below.