GETCHR Function

The GETCHR function enables an online or batch application program to obtain information about the terminal environment in which it is executing or information about the terminal environment for a specified terminal. The information obtained is returned in the form of a table of information referred to as the GETCHR information table. Note that the GETCHR information table should be defined in the working storage area of the application program.

Three arguments are provided by the GETCHR function. The information obtained is placed in a working storage area in the application program indicated by the required area argument. The information supplied is arranged into separate fields, each of which has a length of one to eight bytes.

The optional length argument is used to specify the number of bytes to be returned to the program. If the length argument is not used, Com-plete returns only the first sixteen bytes of information. If specified, the length argument value must end on a GETCHR field boundary.

The optional tid argument enables specification of the terminal to which the GETCHR information pertains. If the TID is omitted, the GETCHR function provides information only for the terminal in use.

The format and content of the GETCHR record are illustrated inGetchr Information Table.

Format
The format for using the GETCHR function is:
GETCHR (retcode,area[,length][,tid]) 
retcode Required.
A fullword where Com-plete places the return code upon completion of the operation.

area Required.
The GETCHR information table area where Com-plete is to place terminal environment information.

length Optional.
Default: If the length is omitted, 16 bytes of information will be provided.A binary halfword containing the number of bytes of terminal environment information to be returned. The contents of length must be a number that ends on a GETCHR field boundary. The length can contain a maximum value of 512.

tid Optional.
Default: If omitted, the environment information returned will be for the TID of the terminal in use. A binary halfword containing the Terminal Identification number (TID) or the Line Identification number (LID) of the terminal or line group about which environment information is being requested.
Return Codes

The following return codes are issued by the GETCHR function:

0 The information returned was for a TID.

4 The information returned was for a LID.

8 The TID/LID number specified exceeds the maximum defined in the TIBTAB.

12 The TID/LID number specified does not exist.

Abends

An abnormal termination may occur during execution of the GETCHR function. Possible causes include:

An invalid argument was specified on the GETCHR call;

A protection exception occurred.

retcode	Required. A fullword where Com-plete places the return code upon completion of the operation.
area	Required. The GETCHR information table area where Com-plete is to place terminal environment information.
length	Optional. Default: If the length is omitted, 16 bytes of information will be provided.A binary halfword containing the number of bytes of terminal environment information to be returned. The contents of length must be a number that ends on a GETCHR field boundary. The length can contain a maximum value of 512.
tid	Optional. Default: If omitted, the environment information returned will be for the TID of the terminal in use. A binary halfword containing the Terminal Identification number (TID) or the Line Identification number (LID) of the terminal or line group about which environment information is being requested.

0	The information returned was for a TID.
4	The information returned was for a LID.
8	The TID/LID number specified exceeds the maximum defined in the TIBTAB.
12	The TID/LID number specified does not exist.