Log Search API

This API searches for information in the Send and Receive Log file (HULFT.LOG) of HULFT based on the specified search conditions.

Since the API works in Language Environment (LE), the CEE.SCEERUN Language Environment library is required. (This is the default name if the library name is defaulted during the installation of the operating system.)

(1) Call Format (COBOL)

CALL 'XRLOGAP' USING parameter area log record area

Explanation of parameter area

Field	Attribute	Length	Description
Operating Version	Character	6	Specify the version of the format of the log record to search for and the version of the parameter area. Specify one of the following: V08L01 V08L02 V08L04 The API obtains the log file fields according to the format of the specified version. Specify the version according to the fields that you want to obtain.
Command	Character	3	Specify one of the following commands for execution:
			GTP	Search for the applicable log information records
			SQP	Set the current position to that of the applicable information record
			GTA	Search for the applicable log information records
			GTN	From the applicable log information record, search for the following information record
			SQN	Read the information record at the current position
			OPN	Open the Send and Receive Log file (HULFT.LOG)
			CLS	Close the Send and Receive Log file (HULFT.LOG)
Execution Option	Character	1	I	Specify this character when you specify 'OPN' for the command
			F	Specify this character when you use a file ID to search for records
			S	Specify this character when you use a host name to search for records
Positioning Option	Character	1	Specify 'H' when you search for information records following the current position.
Reserved	Character	2	Specify LOW-VALUE (0x00).
Search Target Management Information	Character	1	S	Specify this character when you search for records of the Send Log information.
			R	Specify this character when you search for records of the Receive Log information.
			J	Specify this character when you search for records of the Job Execution Log information.
			C	Specify this character when you search for records of the Observe Log information.
Search Key	Character	50	Specify the file ID or host name for which you want to search.
Search Start Date	Binary	4	Specify this field to obtain information records for the applicable date.
Search Start Time	Binary	4	Specify this field to obtain information records for the applicable time. When you specify the search start time, you must specify the search start date.
Status Code	Binary	2	The API sets a status code in this field when the API ends.
VSAM FDBK	Binary	2	When the API ends, the API sets binary data in this field if an error occurs in VSAM access.
Reserved	Character	20	Specify LOW-VALUE (0x00).

[Combinations of Fields]

Command	Execution Option	Positioning Option	Search Key	Search Start Date	Search Start Time	Description
OPN	I	Space	Space	Zero	Zero	Open the Send and Receive Log file (HULFT.LOG).
CLS	Space	Space	Space	Zero	Zero	Close the Send and Receive Log file (HULFT.LOG).
GTP	Space	Space	Space	Zero	Zero	Read the top record according to file ID, date, and time when log records are sorted in EBCDIC order.
SQP	Space	Space	Space	Date	Time	Read the oldest record following the specified date and time.
SQP	Other than space	Space	Space	Zero	Zero	Read the most recent record in date and time among the log records. = Remarks = This command is not applicable to Job Execution logs.
GTA	F	Space	File ID	Zero	Zero	Read the oldest record with the specified file ID.
GTA	F	H	File ID	Date	Zero	Read the oldest record with the specified file ID and date.
GTA	S	Space	Host name	Zero	Zero	Read the oldest record with the specified host name.
GTA	S	H	Host name	Date	Zero	Read the oldest record with the specified host name and date.
GTN	Space	Space	Cannot be changed	Zero	Zero	Read the record that is one record more recent than the last record read.
GTN	F	Space	Cannot be changed	Zero	Zero	Read the record that is one record more recent than the last record read, which has the same file ID as the last record read. (If the API cannot find the same file ID, it returns an error.)
GTN	S	Space	Cannot be changed	Zero	Zero	Read the record that is one record more recent than the last record read, which has the same host name as the last record read. (If the API cannot find the same host name, it returns an error.)
SQN	Space	Space	Cannot be changed	Zero	Zero	Read the record that follows the last record read.
SQN	Other than space	Space	Cannot be changed	Zero	Zero	Read the record that immediately precedes the last-read record.

Note

When you use a combination for which the above table shows Date for the Search Start Date, do not specify zero for the Search Start Date. If you specify zero, the API will not work correctly.

Log record area

The format of the log record area varies depending on the version specified for Operating Version.

For details on the log record area, refer to Log file formats.

Note

When you use the API to obtain records from log files, the API ignores the Key Field that exists in the beginning of each record of a log file. The API obtains the values in the remaining fields in the log file format.

(2) Status Codes

Status Code	Description
0	Execution of the API was completed successfully.
1	The specification of the command is incorrect.
2	The specification for the option is incorrect.
3	Failed to open the Send and Receive Log file (HULFT.LOG).
4	Failed to close the Send and Receive Log file (HULFT.LOG).
7	An error occurred during the search processing. The API sets detailed information in VSAM FDBK.
8	An error occurred in the search processing for the next record of information. The API sets detailed information in VSAM FDBK.
10	The applicable information does not exist.
11	The next record of information does not exist.
14	The operating version is not supported.
15	The specification of the search key is incorrect.
16	The management information record cannot be specified by this command.

Note

Incorporate the following DD statements into the JCL to be executed:

Example of JCL

//XRLOG    DD DSN=HULFT.LOG,DISP=SHR                                            
//XRLOG1   DD DSN=HULFT.LOG.PATH1,DISP=SHR                                      
//XRLOG2   DD DSN=HULFT.LOG.PATH2,DISP=SHR                                      
//XRSYSIN  DD DSN=HULFT.PARMLIB(HULPRM),DISP=SHR

DD Name	Value	Description
XRLOG	HULFT.LOG	Send and Receive Log File ID Key File
XRLOG1	HULFT.LOG.PATH1	Send and Receive Log Host Name Key File
XRLOG2	HULFT.LOG.PATH2	Send and Receive Log Date Key File
XRSYSIN	HULFT.PARMLIB(HULPRM)	System Environment Settings File

(3) Example of Use

Case where you use COBOL

Below is a sample program that searches for records of the Receive Log, using the Log Search API (XRLOGAP).

The sample program has member name 'SMPLOGAP' in HULFT JCL library.

Data to search for

The oldest record of the Receive Log

      * 
      * GET HULFT RECEIVE LOG RECORD SAMPLE 
      * 
       IDENTIFICATION     DIVISION. 
       PROGRAM-ID.         SMPLOGAP. 
       ENVIRONMENT        DIVISION. 
       DATA               DIVISION. 
       WORKING-STORAGE    SECTION. 
      * 
      * XRLOGAP PARAMETER AREA 
      * 
       01  XRLOGAP-PARM. 
           02 XRLOGAP-VER      PIC X(6). 
           02 XRLOGAP-COMMAND  PIC X(3). 
           02 XRLOGAP-EXECOPT  PIC X(1). 
           02 XRLOGAP-POINTOPT PIC X(1). 
           02 XRLOGAP-RESERVE1 PIC X(2). 
           02 XRLOGAP-INFO     PIC X(1). 
           02 XRLOGAP-KEY      PIC X(50). 
           02 XRLOGAP-DATE     PIC 9(8)  COMP. 
           02 XRLOGAP-TIME     PIC 9(8)  COMP. 
           02 XRLOGAP-ERRCD    PIC 9(4)  COMP. 
           02 XRLOGAP-FDBK     PIC 9(4)  COMP. 
           02 XRLOGAP-RESERVE2 PIC X(20). 
      * 
      * XRLOGAP 1 LOG RECORD AREA 
      * 
       01  XRLOGAP-RECORD  PIC X(4000). 
      *------------------------------------------------* 
       PROCEDURE          DIVISION. 
      * 
      * XRLOGAP PARAMETER AREA INITIALIZATION 
      * 
           INITIALIZE XRLOGAP-PARM. 
           INITIALIZE XRLOGAP-RECORD. 
      * 
      * HULFT.LOG OPEN 
      * 
           MOVE 'V08L04'       TO XRLOGAP-VER. 
           MOVE 'OPN'          TO XRLOGAP-COMMAND. 
           MOVE 'I'            TO XRLOGAP-EXECOPT. 
           MOVE LOW-VALUE      TO XRLOGAP-RESERVE1. 
           MOVE 'R'            TO XRLOGAP-INFO. 
           MOVE ZERO           TO XRLOGAP-DATE. 
           MOVE ZERO           TO XRLOGAP-TIME. 
           MOVE LOW-VALUE      TO XRLOGAP-RESERVE2. 
           CALL 'XRLOGAP' USING XRLOGAP-PARM XRLOGAP-RECORD. 
      * 
      * GET THE OLDEST RECORD FROM HULFT RECEIVE LOG FILE 
      * 
           MOVE 'V08L04'       TO XRLOGAP-VER. 
           MOVE 'GTA'          TO XRLOGAP-COMMAND. 
           MOVE 'F'            TO XRLOGAP-EXECOPT. 
           MOVE SPACE          TO XRLOGAP-POINTOPT. 
           MOVE 'R'            TO XRLOGAP-INFO. 
           MOVE 'FILEID'       TO XRLOGAP-KEY. 
           CALL 'XRLOGAP' USING XRLOGAP-PARM XRLOGAP-RECORD. 
           DISPLAY XRLOGAP-RECORD. 
      * 
      * HULFT.LOG CLOSE 
      * 
           MOVE 'V08L04'       TO XRLOGAP-VER. 
           MOVE 'CLS'          TO XRLOGAP-COMMAND. 
           MOVE SPACE          TO XRLOGAP-EXECOPT. 
           MOVE SPACE          TO XRLOGAP-POINTOPT. 
           MOVE 'R'            TO XRLOGAP-INFO. 
           MOVE SPACE          TO XRLOGAP-KEY. 
           MOVE ZERO           TO XRLOGAP-DATE. 
           MOVE ZERO           TO XRLOGAP-TIME. 
           CALL 'XRLOGAP' USING XRLOGAP-PARM XRLOGAP-RECORD. 
      * 
           STOP RUN.