EDITRAN/G 5.2 Application Generic Interface z/os CICS IMS Application Program Interfaces INDRA April 2018
EDITRAN/G 5.2 z/os CICS IMS Interfaces de Programas de Aplicación CONTENTS 1. INTRODUCTION... 1-1 2. INCORPORATION OF MESSAGES IN THE EDITRAN/G LOG... 2-1 2.1. Communication area... 2-1 2.1. Requirements... 2-1 2.2. Example... 2-2 3. PRESENTATION STATUS QUERY... 3-1 3.1. Communication area... 3-1 3.2. Requirements... 3-2 3.3. Example... 3-2 4. FILE QUEUES... 4-1 4.1. Communication area from applications with API... 4-2 4.2. JCL API launching... 4-2 INDRA. All rights reserved. EDITRAN
. 1.INTRODUCTION 1. INTRODUCTION In some developments, the EDITRAN user applications need information about the EDITRAN variables that wish to use internal working resources that can be modified following the product evolution. In order to minimize the impact of these changes on the applications, application programming interfaces are created that are intended to remain stable. The current APIs are listed in the following sections. INDRA. All rights reserved. EDITRAN Page 1-1
2.INCORPORATION OF MESSAGES IN THE EDITRAN/G 2. INCORPORATION OF MESSAGES IN THE EDITRAN/G LOG If an application (user program) needs to record any circumstance related to the EDITRAN/G processes, it could do it by means of the ZTBGB006 module, indicating the session codes, the application and the message, and the text written in representative characters of the message. 2.1. Communication area Level Name Type Length Description 1 Source Alph. 1 Source of the message. U: user message 1 Result Num. 4 Result of the ZTBGB006 execution 1 Direction Alph. 1 E: Input. S: Output. I: Internal. 1 Record syslog Alph. 1 S: the message appears in the system log N: the message is not saved in the system log 1 Presentation Alph. 24 Presentation session associated with the message session 1 Transmission Alph. 24 Transmission session associated with the message. session 1 Message code Num. 4 Code of the message to be recorded 1 Application code Alph. 3 Identification of the user application that owns the message 1 Filler Alph. 18 Reserved area 1 Message Text Alph. 60 Text of the message to be saved 1 Filler Alph. 60 Reserved area 2.1. Requirements It will be necessary to include in the JCL running the user program, a DD tab for the LOG file (ZTBGFLOG) in addition to the EDItran load library. //ZTBGFLOG DD DSN=KI.EIDC.ZTBG.ZTBGFLOG,DISP=SHR In the case of the IMS environment, the ZTBGF032 file must be entered, so that it can write in the log database. //ZTBGF032 DD DSN=KI.EGDI.ZTBG.ZTBGF032,DISP=SHR INDRA. All rights reserved. EDITRAN Page 2-1
2.INCORPORATION OF MESSAGES IN THE EDITRAN/G 2.2. Example The fields that appear in the copy of the ZTBGB006 that are not referred to in the previous section cannot be used. WORKING-STORAGE SECTION. ----------------------- 01 ÁREA-ZTBGB006 PIC X(200) VALUE LOW-VALUES. - - 01 FILLER REDEFINES ÁREA-ZTBGB006. 05 ORIGEN-ZTBGB006 PIC X. 05 CODIGO-RDO-ZTBGB006 PIC 9(4). 05 SENTIDO-ZTBGB006 PIC X(01). 05 GRABAR-SISLOG-ZTBGB006 PIC X(01). 05 SESION-PRESENTACION-ZTBGB006 PIC X(24). 05 SESION-TRANSMISION-ZTBGB006. 07 LOCAL-TRANSMISION-ZTBGB006 PIC X(9). 07 REMOTO-TRANSMISION-ZTBGB006 PIC X(9). 07 APLICA-TRANSMISION-ZTBGB006 PIC X(6). 05 CODIGO-MENSAJE-ZTBGB006 PIC 9(4). 05 PROGRAMA-INC-ZTBGB006 PIC X(8). 05 FILLER REDEFINES PROGRAMA-INC-ZTBGB006. 10 IDENT-MENSAJE-ZTBGB006 PIC X(3). 10 FILLER PIC X(5). 05 RECURSO-INC-ZTBGB006 PIC X(8). 05 RETORNO-INC-ZTBGB006. 10 F-S-INC-ZTBGB006 PIC X(2). 10 RESTO-INC-ZTBGB006 PIC X(3). 05 FILLER REDEFINES RETORNO-INC-ZTBGB006. 10 ERRCOD-INC-ZTBGB006 PIC 9(5). 05 TEXTO-ULT-MSJE-ZTBGB006 PIC X(60). 05 XRESP-ZTBGB006. 10 RESP-ZTBGB006 PIC 9(05). 05 XRAZON-ZTBGB006. 10 RAZON-ZTBGB006 PIC 9(05). 05 FILLER PIC X(50). - - 01 ÁREA-ZTBGB110. 05 LONGITUD-ZTBGB110 PIC 9(4) COMP. 05 ORIGEN-ZTBGB110 PIC X. 05 FUNCION-ZTBGB110 PIC XX. 05 SESION-PRESENTACION-ZTBGB110. 10 LOCAL-ZTBGB110 PIC X(9). 10 REMOTO-ZTBGB110 PIC X(9). 10 APLICACION-ZTBGB110 PIC X(6). 05 FICHCAR-ZTBGB110 PIC X. - LINKAGE SECTION. ---------------- 01 ÁREA-PASO PIC X(29). PROCEDURE DIVISION USING ÁREA-PASO. ----------------------------------- N1-P-PROGRAMA. MOVE LOW-VALUES TO ÁREA-ZTBGB006 MOVE U TO ORIGEN-ZTBGB006 MOVE ZEROS TO CODIGO-RDO-ZTBGB006 MOVE 'E' TO SENTIDO-ZTBGB006 MOVE 'S' TO GRABAR-SISLOG-ZTBGB006 MOVE SESION-PRESENTACION-ZTBGB110 TO SESION-PRESENTACION-ZTBGB006 MOVE LOW-VALUES TO SESION-TRANSMISION-ZTBGB006 MOVE 1331 TO CODIGO-MENSAJE-ZTBGB006 MOVE 'USU' TO IDENT-MENSAJE-ZTBGB006 MOVE 'ESTO ES UNA PRUEBA DE MENSAJE DE USUARIO' TO TEXTO-ULT-MSJE-ZTBGB006 CALL ZTBGB006 USING ÁREA-ZTBGB006. IF CODIGO-RDO-ZTBGB006 NOT = ZEROS DISPLAY 'ERROR EN ZTBGB006, RDO = ' CODIGO-RDO-ZTBGB006. The following appears in the EDITRAN/G LOG query: INDRA. All rights reserved. EDITRAN Page 2-2
2.INCORPORATION OF MESSAGES IN THE EDITRAN/G 05/05/20 15:47:24 CONSULTA FICHERO LOG EDITRAN/G V-5.1 TIPO CODIGO SESION PRESENTACION APL.TRANS. FECHA HORA E U USU1331 000099940 000099990 PRUJCB 05/05/2000 15:37:13 ESTO ES UNA PRUEBA DE MENSAJE DE USUARIO INDRA. All rights reserved. EDITRAN Page 2-3
3.PRESENTATION STATUS QUERY 3. PRESENTATION STATUS QUERY The need for the applications to know automatically the status of the EDITRAN presentation (finished or interrupted), both in transmission and in reception, and for the execution of new processes, has led to the creation of a function in which, if these are fulfilled, it is automatically informed, or a manager is planned to remain in execution until the verification of these statuses or until certain time criteria are met. 3.1. Communication area Level Name Type Length Description 1 Area-gba01 Alph. 250 Communication area of the ZTBGBA01. Used in the CALL. 2 INPUT Alph. 100 Input parameter area Area-parameters 3 Function Num. 2 Requested function: 01.- Presentation status query (finished and interrupted). Depending on the process maximum interval. 02.- Presentation status query (finished and interrupted). Depending on the process maximum limit. 03.- Immediate presentation status query (finished and interrupted). 04.- Query on whether there is a correct status for loading. 3 Direction Alph. 1 (E/R). Direction of the presentation session (transmissionreception) 3 Presentation Alph. 24 Presentation session (source-remote-application) session 3 Wait interval Num. 6 (HHMMSS) Time during which the process must be stopped until the status is checked again to see if the session status has been finished or interrupted. Admitted values: 000000 to 995959. 3 Process maximum Num. 6 FUNCTION 01: (HHMMSS) Time that the active process limit/interval must last if the status criterion is not met in the finished or interrupted status. Admitted values: 000000 to 995959 FUNCTION 02: (HHMMSS) Time until which the process remains active if the status criterion is not met in the finished or interrupted status. If the maximum limit is lower than the start time of the process, it is understood that the maximum limit points to the following day. Admitted values: 000000 to 235959 FUNCTION 03: IGNORED 3 Reservation area Alph. 61 Reservation area 2 OUTPUT Alph. 150 OUTPUT parameter area parameter area 3 Result Num. 2 Process result (00: correct process) 3 Reason Num. 4 Reason returned by the status manager 3 Status of presentation session Num. 3 Status of the transmission presentation session: 000- Loaded. 001- Sending. 002- Sent. 003- Not loaded 004- Suspended 005- Finished Status of the reception presentation session: 100- Initialized 101- Receiving 102- Received 103- Suspended 104- Finished INDRA. All rights reserved. EDITRAN Page 3-1
3.PRESENTATION STATUS QUERY 3 Csb status Num. 3 Loading status of the CSB file: 000- Loaded. 004- Not loaded. 3 Defined presentation Alph. 1 (S/N) (YES/NO) Indicates whether it is defined in the status file. End of process if not, regardless of whether the time criteria have been met. 3 Session Num. Num. 4 Number of presentation session. 3 Present. start date Num. 14 Presentation start date-time (SSAAMMDDHHMMSS). 3 Present. end date Num. 14 Presentation end date-time (SSAAMMDDHHMMSS). 3 Process start date Num. 14 API process start date-time (SSAAMMDDHHMMSS) 3 Process end date Num. 14 API process end date-time (SSAAMMDDHHMMSS) 3 Interval-Num Num. 8 Number of WAIT intervals performed in the process 3 Reservation area Alph. 69 Reservation area The result codes returned are (the reason is independent of the result, and it identifies the code returned by the ZTBGB009): Result Reason Description 0 Xx Process carried out correctly. 01 Xx Wrong function parameter (other than 01, 02, 03, 04). 02 Xx Wrong direction parameter (other than E - R) 03 Xx Wrong presentation session parameter (spaces-low values or zeros) 04 Xx Wrong wait interval parameter (non-numeric or it has no hhmmss format) (000000 to 995959) 05 Xx With function 01 and 02 Wrong maximum interval parameter (non-numeric or it has no hhmmss format) In function 01: (000000 to 995959) In function 02: (000000 to 235959) 06 Xx Presentation not defined in the status file (error returned by ZTBGB009). It may be defined in profiles, but there has never been an action on the presentation. Immediate end of process. 07 Xx The time limit-interval of the API execution has been reached and the FINISHED-INTERRUPTED statuses have not been achieved. 08 Xx Wrong process in ZTBGB009 program. Query EDITRAN/G codes. Immediate end of process. 09 Xx During a wait interval, when performing a new status query, the session has been modified and a new one has been created (for example, it has finished and has been reloaded). Immediate end of process. 34 Xx The upload is not allowed. 3.2. Requirements It will be necessary to include in the JCL running the user program, a DD tab for the Status file (ZTBGFEST) and an optional one for the LOG file (ZTBGFLOG). //ZTBGFLOG DD //ZTBGFEST DD DSN=KI.EIDC.ZTBG.ZTBGFLOG,DISP=SHR DSN=KI.EIDC.ZTBG.ZTBGFEST,DISP=SHR 3.3. Example The ZTBGBA01 copy. WORKING-STORAGE SECTION. ----------------------- 01 ÁREA-ZTBGBA01 PIC X(250). 01 FILLER REDEFINES ÁREA-GBA01. 05 ÁREA-ENTRADA-GBA01 PIC X(100). INDRA. All rights reserved. EDITRAN Page 3-2
3.PRESENTATION STATUS QUERY 05 FILLER REDEFINES ÁREA-ENTRADA-GBA01. 10 FUNCION-GBA01 PIC 9(2). 10 SENTIDO-GBA01 PIC X. 10 SESION-PRESENTACION-GBA01. 15 LOCAL-GBA01 PIC X(9). 15 FILLER REDEFINES LOCAL-GBA01. 20 FILLER PIC X. 20 LOCAL-2-GBA01 PIC X(7). 20 FILLER PIC X. 15 REMOTO-GBA01 PIC X(9). 15 FILLER REDEFINES REMOTO-GBA01. 20 FILLER PIC X. 20 REMOTO-2-GBA01 PIC X(7). 20 FILLER PIC X. 15 APLICACION-GBA01 PIC X(6). 10 INTERV-WAIT-GBA01 PIC X(6). 10 FILLER REDEFINES INTERV-WAIT-GBA01. 15 HH-WAIT-GBA01 PIC 9(2). 15 MM-WAIT-GBA01 PIC 9(2). 15 SS-WAIT-GBA01 PIC 9(2). 10 INTERV-MAX-GBA01 PIC X(6). 10 FILLER REDEFINES INTERV-MAX-GBA01. 15 HH-MAX-GBA01 PIC 9(2). 15 MM-MAX-GBA01 PIC 9(2). 15 SS-MAX-GBA01 PIC 9(2). 10 LIMITE-MAX-GBA01 REDEFINES INTERV-MAX-GBA01. 15 HH-LIM-MAX-GBA01 PIC 9(2). 15 MM-LIM-MAX-GBA01 PIC 9(2). 15 SS-LIM-MAX-GBA01 PIC 9(2). 10 FILLER PIC X(61). 05 ÁREA-SALIDA-GBA01 PIC X(150). 05 FILLER REDEFINES ÁREA-SALIDA-GBA01. 10 RESULTADO-GBA01 PIC 9(2). 10 RAZON-GBA01 PIC 9(4). 10 EST-SES-PRESENT-GBA01 PIC 9(3). 10 EST-CARGA-CSB-GBA01 PIC 9(3). 10 PRESENT-DEFINIDA-GBA01 PIC X(1). 10 NUM-SESION-GBA01 PIC 9(4). 10 FECHA-INICIO-PRES-GBA01 PIC X(14). 10 FILLER REDEFINES FECHA-INICIO-PRES-GBA01. 15 WFECH-INI-PRES-GBA01 PIC X(8). 15 WHORA-INI-PRES-GBA01 PIC X(6). 10 FECHA-FIN-PRES-GBA01 PIC X(14). 10 FILLER REDEFINES FECHA-FIN-PRES-GBA01. 15 WFECH-FIN-PRES-GBA01 PIC X(8). 15 WHORA-FIN-PRES-GBA01 PIC X(6). 10 FECHA-INICIO-PROC-GBA01 PIC X(14). 10 FECHA-FIN-PROC-GBA01 PIC X(14). 10 INTERV-EJ-GBA01 PIC 9(08). 10 FILLER PIC X(69). PROCEDURE DIVISION. N1-P-PROGRAMA. MOVE LOW-VALUES TO ÁREA-GBA01 MOVE 01 TO FUNCION-GBA01. MOVE E TO SENTIDO-GBA01. MOVE 000099990 TO LOCAL-GBA01 MOVE 000099940 TO REMOTO-GBA01 MOVE PRUEBA TO APLICACION-GBA01 INTERVALOS DE WAIT CADA 5 MINUTOS Y MEDIO. INTERVALO MAXIMO DE ESPERA: 31 HORAS, 59 MINUTOS, 14 SEGUNDOS MOVE 000530 TO INTERV-WAIT-GBA01 MOVE 315914 TO INTERV-MAX-GBA01 MOVE ÁREA-ENTRADA-GBUTC TO ÁREA-ENTRADA-GBA01. CALL ZTBGBA01 USING ÁREA-GBA01. IF RESULTADO-GBA01 = ZEROS OR 07 IF ESTADO-PRESENTACION-GBA01 = 005 DISPLAY FINALIZADO AQUI SE PODRIAN REALIZAR LAS ACCIONES DESEADAS ELSE DISPLAY ESTADO : ESTADO-PRESENTACION-GBA01 INDRA. All rights reserved. EDITRAN Page 3-3
3.PRESENTATION STATUS QUERY ELSE NEXT SENTENCE. MOVE RESULTADO-GBA01 TO RETURN-CODE. INDRA. All rights reserved. EDITRAN Page 3-4
EDITRAN/G 5.2 z/os CICS IMS Interfaces de Programas de Aplicación 4.FILE QUEUES 4. FILE QUEUES To see the graphical interface, refer to the manuals: EDITRAN/P Graphical interface. User Manual (ED52USUC) for CICS or EDITRAN/G User Manual (EG52USUI) for IMS. The functionality of the file queues is that the applications notify the files they want to send or upload and ignore whether or not EDITRAN can do it at that time. There is a file (ZTBPGFQF) whose contents are a profile for each presentation session involved, and the transmission files pending or in transmission. To work with this option, it is necessary: To define the TYPE-LOAD = Q parameter in the presentation session (option 2.3.4 of the main menu). To define the presentation session in the file queues profile (option 2.4.2). If the session is not defined, it is created automatically when the API is called from the applications (no schedule, load+transmission, depth 1 and active). To call the API from the applications, indicating the function (save-delete), the presentation session, the file name to load-send and its characteristics (format, language, translation and compression). The API can also be called with a JCL. EDITRAN saves in a storage queue - ZTBGFQF file in CICS, and ZTBGDQFD/I DB in IMS: The profile of the presentations with their parameters: start time, end time, if we want to load or to load and send. If we want to have activity or to stop, if we want to send a single file or all the available ones, or a certain number, etc. Each one of the files indicated by the API from the applications and their status (pending process= pending, in process = sending). The operation schema is the following: There is a manager, which is started every xx minutes (according to the EDITRAN/P local environment parameter), that verifies if there are pending files (to upload or send). If this is the case and the session is in a compatible status, meets the time limits and has activity, and in the presentation session is of the 'Q' type, a process before transmission is launched (the one indicated in the presentation session, with the JCL files of the first presentation transmission in CICS, and in the presentation session in IMS). When launching the process before transmission, if the presentation session has in its profile the queue loading mode, `Q': o It verifies that the EDITRAN/G status is compatible for loading (not loaded, finished, initialized). If not, it ends the process. o It verifies that there are no files in the storage queue in the "sending" status. If there are, the process ends. If this situation arises from an exception, a procedure of transmission status modification must start. o It sets the file(s) to be uploaded in the sending status. o It loads them into the buffer. o It requests EDITRAN/P to load and/or send according to the file queue profile. INDRA. All rights reserved. EDITRAN Page 4-1
EDITRAN/G 5.2 z/os CICS IMS Interfaces de Programas de Aplicación 4.FILE QUEUES When launching the process after transmission, if the presentation session has type-load = Q in its profile, it deletes the files in the sending status from the storage queue. When starting the modification of the transmission statuses, if the presentation session has type-load = Q in its profile, it passes the files that are in the 'sending' status to the pending' status, provided that it does not duplicate the file name, with another one recorded as 'pending', in which case it deletes the one that was in the 'sending' status. 4.1. Communication area from applications with API It is used to call to API from the applications. Level Name Lengt Format Description h 1 Communication area 100 Alph. Communication area with API 2 Reserved 02 Num-B. Reserved. If jcl is launched, this field does not exist 2 Return code 02 Num-B. Return code. In case of launching the attached jcl, reserved field 2 Function 02 Num. Function: 01- Save files 02- Delete all pending files 2 Presentation 24 Alph. EDITRAN/G session where files are sent. 3 Source 9 Alph. Source Tax Id. Nr. 3 Destination 9 Alph. Destination Tax Id. Nr. 3 Application 6 Alph. EDITRAN/G Application 2 Type 1 Num. F: File (include file) L: File list (include file list) 2 File 44 Alph. If type L: Name of the list of files containing the files to be saved in the queue. If type F: Name of the MVS file to be queued. File up to 44 positions. 2 Load format 1 Alph. Format (R)ecord-(M)odified. If spaces, R 2 Language 1 Alph. Original language (E)bcdic, (A)scii, (B)inary. If spaces, it takes presentation session profile parameter. 2 Translate 1 Alph. Translate into Transmission (E)bcdic, (A)scii, (N)one. If spaces, it takes presentation session profile parameter. 2 Compression 1 Alph. F/N compression. If spaces, it takes presentation session profile parameter. 2 Filler 21 Alph. Reservation area 4.2. JCL API launching There are two JCLs to call the API: In CICS The JCL is ZTBGJGQF. The previous communication area is passed in 2 ways: 1. Through PARM 2. Through the ZTBGFGQF file In IMS 3. JCL ZTBGJGQF will pass the communication area via PARM 4. JCL ZTBGJEQF will pass the communication area through the ZTBGFGQF file. INDRA. All rights reserved. EDITRAN Page 4-2
ECommerce Competence Centers Avda. de Bruselas 35 28108 Alcobendas. Madrid, Spain T. +34 91 480 80 80 T. +34 91 480 50 00 www.indracompany.com