U@GENERICAPI

U@GENERICAPI is a gateway API from a RPG program to the runtime system (larpgrts). It contains one or more hidden API calls. After connecting to the runtime system, this API branches to the hidden APIs. The purpose of this API is to allow a new API to be implemented in RPG before it is fully implemented in the runtime system. This means that a specific RPG release does not have be tied to a specific level of APIs in the runtime system.

U@GENERICAPI works as a validation function to check if an API is implemented in the current version of the runtime system. Each RPG program must provide two paths: one for when the API is implemented and one for when it is not.

Module SYSCMDS

Input

Field Definition
E@GNAPAPIINDEX

Number indicating which of the hidden APIs is called by the Generic API. Valid values are from 1 to 99. A special test API has already been assigned a value of 90, so any new hidden APIs do not have this value. To call the hidden API, the RPG program must have the index value for the hidden API:

2 = calls the hidden API that gets the size of the file. You must provide the file (in full path) using the E@GNAPINPRMS. The E@GNAPOUTPRMS contains the file size.

3 = calls the hidden API that supports the copy of different file types to the destination directory.
Note: You must provide directory (in full path) of the source file and the destination directory. This functionality does not support direct folder copy and will only accept single file copy.

4 = calls the hidden API that creates directory along with any required parent directories. You must provide the directory (in full path) using the E@GNAPINPRMS, with the limitation of reading only the first 100 characters. The E@GNAPOUTPRMS does not contain any significant value; it remains an empty string.

7 = calls the hidden API that creates empty file/s. You must provide the full path filenames, separated by space, using the E@GNAPINPRMS. The total length should not exceed 3000 characters, and avoid including special characters. The E@GNAPOUTPRMS does not contain any significant value; it remains an empty string.
E@GNAPFUNC Indicates the Generic API function to be performed: "V" = Validate that the hidden API exists. "R" = Run the hidden API.
E@GNAPINPRMS Parameter Buffer sent to the hidden API in the runtime system. 3000 bytes. (Optional)

Output

Field Definition
E@GNAPRESULT Result of Generic API call: Found/NotFound/Successful/Failed.
E@GNAPERROR Contains a three-digit error number and a 100-byte error message if the result value is "Failed." If the E@GNAPRESULT field has a value of "FAILED," then the two parts of the E@GNAPERROR field should be populated. When an API is run, the result values should be SUCCESSFUL or FAILED.
E@GNAPOUTPRMS Parameter buffer containing the data returned by the hidden API. 3000 bytes.

Programming Example

This information outlines how to use U@GENERICAPIVL together with U@GENERICAPI to check for the existence of an API and then call that API. (U@NEWAPISETUP and U@NEWAPIRETURN are not API references, but are placeholders for whatever actual API was being implemented.)

    EVAL      E@GNAPAPIINDEX = E@APIINDEXVAL
    CALLP     U@GENERICAPIVL                               Generic Api Validati
    
    IF        E@GNAPRESULT = *ZEROS
    GOTO      U@OLDCODEPATH
    
    ELSE
    CALLP     U@NEWAPISETUP
    EVAL      E@GNAPFUNC     = 'R'
    CALLP     U@GENERICAPI                                 Generic Api
    
    IF        E@GNAPRESULT = 999
    
    CALLP     U@STR@INIT(%ADDR(E@STR@DS): *NULL: 1: 41:
              1)
    CALLP     U@STR@ITEMSZ(%ADDR(E@STR@DS):
              'API Failed Error: ': 1: 18)
    EVAL      E@STR@PRTFLD   = %CHAR(E@GNAPERRNBR)
    CALLP     U@STR@ITEMSZ(%ADDR(E@STR@DS):
              E@STR@PRTFLD: 1: %LEN(E@STR@PRTFLD))
    CALLP     U@STR@PRT(%ADDR(E@STR@DS): 1)
    
    
    CALLP     U@STR@INIT(%ADDR(E@STR@DS): *NULL: 1:
              131: 1)
    CALLP     U@STR@ITEMSZ(%ADDR(E@STR@DS):
              'Error Msg: ': 1: 11)
    CALLP     U@STR@ITEMSZ(%ADDR(E@STR@DS):
              E@GNAPERRMSG: 1: %SIZE(E@GNAPERRMSG))
    CALLP     U@STR@PRT(%ADDR(E@STR@DS): 1)
    
    ELSE
    CALLP     U@NEWAPIRETURN
    
    ENDIF
    ENDIF