OpenTP1 Version 7 Programming Reference COBOL Language

[Contents][Index][Back][Next]

CBLDCADM ('COMMAND ') - Execute an operation command

Format

PROCEDURE DIVISION specification

CALL  'CBLDCADM'  USING  unique-name-1 unique-name-2
                         unique-name-3 unique-name-4

DATA DIVISION specification

01  unique-name-1.
    02  data-name-A    PIC X(8) VALUE 'COMMAND '.
    02  data-name-B    PIC X(5).
    02  FILLER       PIC X(3).
    02  data-name-Z    PIC S9(9) COMP VALUE ZERO.
    02  data-name-C    PIC S9(9) COMP.
01  unique-name-2.
    02  data-name-E    PIC 9(9) COMP.
    02  data-name-G   PIC X(n).
01  unique-name-3.
    02  data-name-H    PIC 9(9) COMP.
    02  data-name-J    PIC X(n).
01  unique-name-4.
    02  data-name-K    PIC 9(9) COMP.
    02  data-name-M   PIC X(n).

Description

CBLDCADM('COMMAND ') passes data name G from the UAP to sh(1) as in the case of command entry in online mode. The process waits until the shell completes its processing, and returns the exit status of the shell. When the command processing ends, the standard output information and standard error information are returned to the respective areas.

If you want to use UAPs which execute a command, add the directory containing the commands to the search path. Use any of the following methods for addition to the search path.

Data areas whose values are set in the UAP

data-name-A

Specify VALUE 'COMMAND[Figure]' for the request code of the command to be executed.

data-name-Z

Specify 0.

data-name-E

Specify the length of the command set for data-name-G.

data-name-G

Specify the character string of the command.

data-name-H

The execution results of the command are output to the standard output file. Specify the size of the contents (value returned to data-name-J) in bytes. Pre-allocate the area in size of the number of bytes that is to be specified for data-name-H. The area must begin from the address pointed to by data-name-J. The number of bytes to be specified for data-name-H must be decided according to the command executed by the UAP.

After processing terminates, the length of the character string stored in data-name-J is returned from OpenTP1. The length of data-name-H itself is not included.

data-name-K

The execution results of the command are output to the standard error output file. Specify the size of the contents (value returned to data-name-M) in bytes. Pre-allocate the area in size of the number of bytes that is to be specified for data-name-K. The area must begin from the address pointed to by data-name-M. The number of bytes to be specified for data-name-K must be decided according to the command executed by the UAP.

After processing terminates, the length of the character string stored in data-name-M is returned from OpenTP1. The length of data-name-K itself is not included.

Data areas to which values are returned from OpenTP1

data-name-B

A status code of 5 digits is returned.

data-name-C

A shell termination code# is returned indicating whether the command terminated normally or abnormally.

#: Denotes an sh(1) termination status in the format specified by waitpid(2).

data-name-H

The length of the character string stored in data-name-J is returned after processing terminates. The length of data-name-H itself is not included.

data-name-J

This area stores characters output to the standard output file by the operation command. The maximum length of a character string which can be stored is as specified for data-name-H. If the length of a character string exceeds the value specified for data-name-H, the excess characters are truncated. If the character string exceeds the capacity of the pipe, the excess characters are also truncated.

data-name-K

The length of the character string stored in data-name-M is returned after processing terminates. The length of data-name-K itself is not included.

data-name-M

This area stores characters output to the standard error output file by the operation command. The maximum length of a character string which can be stored is as specified for data-name-K. If the length of a character string exceeds the value specified for data-name-K, the excess characters are truncated. If the character string exceeds the capacity of the pipe, the excess characters are also truncated.

Status codes

Status code Explanation
00000 The shell termination code is 0 (normal termination of the command execution). The character string was stored in the standard output area and the standard error output area.
01801 The shell termination code is not 0 (abnormal termination of the command execution). Standard output data and standard error output data were stored in the areas.
01802 The value specified for the data name is invalid. This error also occurs if the request code (data-name-A) is invalid.
01803 All the standard output data could not be stored in the area.
01804 All the standard error output data could not be stored in the area.
01805 Both the standard output data and the standard error output data could not be stored in the areas.
01806 A system call (close, pipe, dup, or read) could not be executed.
01807 CBLDCRPC('OPEN ') was not called.
01808 The memory became insufficient.

Note

Be careful not to duplicate the command name between directories that are specified as search paths. The correct command will not execute if the command name is duplicated. In addition, be careful not to duplicate the command name with that of the command group provided by OpenTP1 (under $DCDIR/bin).