Micro Focus Visual COBOL 2.3 Update 2 for Visual Studio 2012 > General Reference > Library Routines > Alphabetical List of Library Routines > CBL_GET_PROGRAM_INFO

Micro Focus Visual COBOL 2.3 Update 2 for Visual Studio 2012 > General Reference > Library Routines > Program Information Routines > CBL_GET_PROGRAM_INFO

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.2.
   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:

The basename of the program for which information is required.

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-24

Reserved for future use - must be set to 0.

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.