900-GENERIC-API

900-GENERIC-API is a gateway API from a 4GL program to the runtime system (lacobrts). 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 4GL before it is fully implemented in the runtime system. This means that a specific 4GL release is not required to be tied to a specific level of APIs in the runtime system.

900-GENERIC-API works by using a validation function to check if an API is implemented in the current version of the runtime system. Each 4GL program must provide two paths: one for when the API is implemented and one for when it is not.


`Library`	SYSCMDS

Input


Field	Definition
`GENAPI-API-INDEX`	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 4GL 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 `GENAPI-INPUT-PMS`. The `GENAPI-API-OUTPUT-PRMS` 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 `GENAPI-INPUT-PMS`, with the limitation of reading only the first 100 characters. The `GENAPI-API-OUTPUT-PRMS` 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 `GENAPI-INPUT-PRMS`. The total length should not exceed 3000 characters, and avoid including special characters. The `GENAPI-API-OUTPUT-PRMS` does not contain any significant value; it remains an empty string.
`GENAPI-FUNCTION`	Indicates the Generic API function to be performed: "V" = Validate that the hidden API exists. "R" = Run the hidden API.
`GENAPI-INPUT-PRMS`	Parameter Buffer sent to the hidden API in the runtime system. 3000 bytes. (Optional)

Output


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

Programming Example

This information shows how to use 900-GENERIC-API-VALIDATION together with 900-GENERIC-API to check for the existence of an API and then call that API. (900-NEW-API-SETUP and 900-NEW-API-RETURN are not API references, but are only placeholders for whatever actual API was being implemented.)

	MOVE WS-API-INDEX-VALUE       TO GENAPI-API-INDEX.
	PERFORM 900-GENERIC-API-VALIDATION.
	IF (GENAPI-NOTFOUND)
	    GOTO 000-OLD-CODE-PATH
	ELSE
	    PERFORM 900-NEW-API-SETUP
           MOVE "R"                   TO GENAPI-FUNCTION 
	    PERFORM 900-GENERIC-API
           IF (GENAPI-FAILED)
		  DISPLAY "API Failed Error: ", GENAPI-ERROR-NBR
		  DISPLAY "Error Msg: ", GENAPI-ERROR-MSG           
	     ELSE
		  PERFORM 900-NEW-API-RETURN.