API Calling Requirements

Generic Data Transfer Application Event Support › API Calling Requirements

API Calling Requirements

Call NM000FGX (the API) once for each data transfer event. The standard linkage conventions apply. Ensure that NM000FGX is loaded either before the first call or by the first call.

The coding requirements are:

Initialize the generic event record to spaces. The assembler macro provided generates the dummy section (DSECT) mapping the generic event.
Set the various fields as needed ( the Transfer Id and Event Type are mandatory).
Place the address of the generic event record in the first and only word of a Parameter List.
Set register 1 to point to a Parameter List.
Call NM000FGX.
NM000FGX returns a completion code through register 15. A return code of 0 indicates that the generic event was validated and forwarded through the Simple One-Shot Event Sender facility to the appropriate File Transfer regions. A return code other than 0 indicates an error condition.

The following diagram shows how the information is passed to the API:

Shows how information is passed to the API

Example Code

The following example shows a generic event API. You can add it to the relevant logic (for example, the exit) of your data transfer application.

Note: You can use the Browse Event and Transfer Details option on the History Data menu (/FTHIST.B) to verify that your modified application works correctly. Select List All File Transfer Events, and verify that the generic transfer events are visible.

*        .-----------------------------------------.
*        | Event addressability                    |
*        |                                         |
*        |  Register assignments are sample only.  |
*        '-----------------------------------------'
         LA    R9,EVENT
         USING GEVENT,R9
*
*        .-----------------------------------------.
*        | Check if the NMFT API was Loaded        |
*        '-----------------------------------------'
         L     R1,GEVTEP                Get NM000FGX entry point addr.
         LTR   R1,R1
         BNZ   BLDEVENT                 Already loaded, Build event
         CLC   GEVTR15,=F'0'            Did a prior Load failed?
         BNE   ??????                     - Yes, report error (may be)
*
*        .------------------------------------------------------.
*        |   I n i t i a l i s z a t i o n   (maybe)            |
*        |                                                      |
*        | LOAD the NMFT API module (NM000FGX)                  |
*        '------------------------------------------------------'
         LOAD  EP=NM000FGX              LOAD
         ST    R15,GEVTR15              Save Return Code
         LTR   R15,R15                  Load failed ?
         BNZ   ??????                     - Yes, report error (may be)
         ST    R0,GEVTEP                Save Entry point
*
*        .-----------------------------------------.
*        | Set NM000FGX parameter List             |
*        '-----------------------------------------'
         ST    R9,GENEVTAD              Set Gen Event pointer
         OI    GENEVTAD,X'80'           Flag it as last in list
*
*        .-----------------------------------------.
*        | The NMFT API was successfully Loaded    |
*        '-----------------------------------------'
*        ooo      xxxxxx,xxxxxx         Whatever is required (i.e: WTO)
*        ...      ......
BLDEVENT EQU   *
*        .------------------------------------------------------.
*        |  A s s e m b l e   t h e    e v e n t   f i e l d s  |
*        |                                                      |
*        | Note: Register assignments are sample only.          |
*        '------------------------------------------------------'
*
*        .-----------------------------------------.
*        | Initialise the Event record with spaces |
*        '-----------------------------------------'
         LR    R4,R9
         LA    R5,GEVENTLG
         XR    R3,R3
         ICM   R3,B'1000',=C' '
         MVCL  R4,R2
*        .-----------------------------------------.
*        |       Build the Event record            |
*        | Note: Only GEXFRID and GETYPE are       |
*        |       required all other fields are     |
*        |       Optional.                         |
*        '-----------------------------------------'
         MVC   GEXFRID,=CL32'MYTRANSFER(00001)'       *< REQUIRED >*
         MVI   GETYPE,GESTART                         *< REQUIRED >*
         MVC   GEDXPRD,=CL24'ACME-DATASTAR Ver 06.2'
         MVC   GESRCNOD,=CL20'HEAD-OFFICE.NODE001'
         MVC   GESRCDAT,=CL256'NEW.YEARLY.RATES'
         MVC   GETRGNOD,=CL20'OVERTHERE.BRANCH'
         MVC   GETRGDAT,=CL256'/master/rates.data'
         MVC   GEUSRDAT,=CL32'Sample Start Event'
         MVC   GEUSERID,=CL16'ACCOUNTU0001'
*
CALLAPI  EQU   *                        RETURN OK
*        .------------------------------------------------------------.
*        |  CALL the NMFT API module (NM000FGX)                       |
*        '------------------------------------------------------------'
         LA    R1,PARMLIST              R1 -> Parameter list
         L     R15,GEVTEP               R15 -> NM000FGX
         BASSM R14,R15                  CALL EXIT MODULE
*
FGXRETRN EQU   *
         LTR   R15,R15                  Call returned in error ?
         BNZ   ??????                   - Yes, report error (may be)
*
*        ooo      xxxxxx,xxxxxx         Whatever
*        ...      ......
*
*        *--------*   D A T A   A R E A    *----------*
*        .-----------------------------------------.
*        | NMFT API (NM000FGX) Parameter List      |
*        '-----------------------------------------'
PARMLIST DS    0D                       NM000FGX Parameter List
GENEVTAD DS    A(0)                     Generic Event Address
*
*        .-----------------------------------------.
*        | NMFT API (NM000FGX) Load control        |
*        '-----------------------------------------'
GEVTEP   DC    F'0'                     NM000FGX Entry Point Address
GEVTRC   DS    0F                       RETURN CODES
GEVTR15  DC    F'0'                     - R15
GEVTR0   DC    F'0'                     - R0
*
*---------------------------------------------------------------------*
*        Generic event                                                *
*---------------------------------------------------------------------*
EVENT    DS    0D
         DS    CL(GEVENTLG)' '
*
*---------------------------------------------------------------------*
*     DSECTS                                                          *
*---------------------------------------------------------------------*
         $RFGEVNT