CallAPIs are used to trigger processes in the AE from external systems by using the Automation Engine scripting language. You can start executable objects, set or can read contents of variable objects, or can get specific information about the status of tasks. As an administrator, you set up the CallAPI, specify login data, connect to the AE, and define your platform-specific parameters. You can use the CallAPI either with your own program, or with a utility. The Automation Engine scripting language is limited to 32000 characters in any case.
This page includes the following:
Log in to the AE system
To log in to the AE system, the CallAPI requires a valid user credentials. A user must have the privilege Logon via CallAPI and must have Execute rights.
You can specify your login data (client, user, department, and password) in the INI file of the CallAPI. Alternatively, you specify it when you call the CallAPI.
You can encrypt your password by using the program UCYBCRYP.EXE. The encrypted string must not exceed 64 characters. For details, see Encoding Passwords.
No password verification takes place when you use single logon for your CallAPI. To do so, store the relevant data in the system variable UC_USER_LOGON. For details, see UC_USER_LOGON - Single Logon.
Connect to the Automation Engine
To activate your script in the required AE system, the CallAPI requires connection information for relevant communication processes. Enter this connection information in the INI file (such as 2217=localhost). In CallAPI calls from your own programs, you can directly assign it.
Messages
If you use a Job object that calls the CallAPI utility, you can see the related messages in the job report.
You can use the :STOP script statement to assign message numbers and texts to the CallAPI. They are stored in script variables and can be read with your own programs. The names of these variables depend on the programming language you are using. Depending on the stop mode that you define in the script statement :STOP, the script either aborts or continues to run.
Use the CallAPI with your Own Program
You can use the CallAPI to process scripts in the AE system from your own programs that are written in C, C++, Cobol, Java, or Visual Basic. Sound knowledge of the programming language in which the program is written is required for this purpose.
Scripts are always activated with the following three steps:
- Log in to the AE system.
- Transfer the script to the AE system.
- Log off from the AE system.
You can log in to several AE systems at the same time and process various scripts.
CallAPI with C, C++
The delivery directory contains sample programs that provide a detailed description of how you call the CallAPI. The file uccall3.h provides information about structure and functions.
Functions
You can use the several functions in your programs. They supply return code 0 if the action was successful, or a message number if an error occurred. The data type of all return codes is long.
- UCCALL3_Logon (structure, login data, connection)
Use it to log in to the AE system
Data type of structure: UCCALL_PARAMS*
Data type of login data: char*
Data type of connection: char* - UCCALL3_ActivateScript (structure, script)
Use it to activate a script
Data type of structure: UCCALL_PARAMS*
Data type of script: char* - UCCALL3_Logoff (structure)
Use it to log off from the AE system
Data type of structure: UCCALL_PARAMS* - UCCALL3 (structures)
Universal function
UCCALL3 can be called instead of the functions described above. In this case, indicate the opcode in the structure in order to have the required operation processed.
Data type of structure: UCCALL_PARAMS*
Format of login data: client, user, [department, [password]]
Format of connection data for the communication process: DNS name:port number or TCP/IP address:port number
Variables
Information such as the system name or the RunID of the script is stored in the structure UCCALL_PARAMS. It contains the following variables:
- cOpCode
Data type: char [4]
Operation code
This variable must be set if the universal function should be used. - OPC_LOGON
Logs in to the AE system - OPC_LOGOFF
Logs off the AE system - OPC_ACTIVATE_SCRIPT
Activates a script - cErrorCode
Data type: char
Allowed values:
The error code in cErrorCode is automatically set and can contain one of the following values:
- " "
No error occurred - P
Invalid parameter(s) - O
Invalid opcode - Q
Login failed - R
Memory allocation failed - L
Memory release failed - S
Socket error - T
Timeout - U
Error message of the AE system - cInterface
Data type: char [3]
The interface number must always contain the value 3. - cSystemName
Data type: char [8]
Name of the AE system to which the connection should be established - sTimeout
Data type: unsigned short
Period in seconds during which the CallAPI waits for an AE system response - cLanguage
Data type: char
Language in which messages are output - cFlag1
Data type: unsigned char
- CALL_FLAG1_INI_SERVER
Connection to communication process is retrieved from INI file - CALL_FLAG1_INI_LOGIN
Login data is retrieved from INI file - CALL_FLAG1_INI_USEMSL
Converts variable message parts to a complete message text - CALL_FLAG1_INI_USEALL
Settings made in the INI file section [GLOBAL] are used - CALL_FLAG1_TRC_HANDLE
For internal CallAPI processing only - CALL_FLAG1_LOG_HANDLE
For internal CallAPI processing only - CALL_FLAG1_INI_FILE
Name of INI file - CALL_FLAG1_TRC_OUTPUT
For internal CallAPI processing only - lUnused1
Data type: unsigned long [4]
Not used - Output
Data type: unsigned long
Not used - lUnsued2
Data type: unsigned long [4]
Not used - lScriptRunNr
Data type: unsigned long
RunID of the script - lRetCode
Data type: unsigned long
Return code of script execution - cRetText
Data type: char [256]
Variable message part that explains the value of the return code - pIniFile
Data type: char*
Path and name of INI file - hZuLog
Data type: unsigned long
For internal CallAPI processing only - hZuTrc
Data type: unsigned long
For internal CallAPI processing only - hZuHlp
Data type: unsigned long
For internal CallAPI processing only - lUnused3
Data type: unsigned long [11]
Not used - pOwnPointer
Data type: void*
For internal CallAPI processing only
Depending on the specified value, this flag results in one of the following processing options:
CallAPI with Cobol
You call the CallAPI by using the command CALL UCCALL3. Return code 0 is supplied if the action was successful or a message number if an error occurred.
- CALL UCCALL3 USING structure, login data, connection
Use it to log in to the AE system
Format of login data: Client, user, [department, [password]]
Format of connection data for the communication process: DNS name:port number or TCP/IP address:port number - CALL UCCALL3 USING structure, script
Use it to activate a script - CALL UCCALL3 USING structure
Use it to log off from the AE system
Variables
The supplied sample program explains the structure AE-RECORD. It contains the following variables:
- UC-OPERATION
Data type: PIC X(4)
Operation code
This variable must be set if the universal function should be used. - OPC_LOGON
Logs on to the AE system - OPC_LOGOFF
Logs off the AE system - OPC_ACTIVATE_SCRIPT
Activates a script - UC-ERROR-CODE
Data type: PIC X - " "
No error occurred - P
Invalid parameter(s) - O
Invalid opcode - I
Initialization failed - Q
Login failed - R
Memory allocation failed - L
Memory release failed - S
Socket error - T
Timeout - U
Error message of the AE system - UC-INTERFACE-NR
Data type: PIC X(3)
The interface number must always contain the value 3. - UC-SYSTEM-NAME
Data type: PIC X(8)
Name of the AE system to which the connection should be established - UC-TIMEOUT
Data type: PIC 9(4) COMP-4
Time in seconds during which the CallAPI waits for an AE system response - UC-LANGUAGE
Data type: PIC X
Language in which messages are output - FILLER
Data type: PIC X(2)
Not used - UC-FLAG1
Data type: PIC X - CALL_FLAG1_INI_SERVER
Connection to communication process is retrieved from INI file - CALL_FLAG1_INI_LOGIN
Login data is retrieved from INI file - CALL_FLAG1_INI_USEMSL
Converts variable message parts to a complete message text - CALL_FLAG1_INI_USEALL
Settings made in the INI file section [GLOBAL] are used - CALL_FLAG1_TRC_HANDLE
For internal CallAPI processing only - CALL_FLAG1_LOG_HANDLE
For internal CallAPI processing only - CALL_FLAG1_INI_FILE
Name of INI file - CALL_FLAG1_TRC_OUTPUT
For internal CallAPI processing only - FILLER
Data type: PIC X(2)
Not used - UC-OUTPUT-LEN
Data type: PIC 9(8) COMP-4
Not used - UC-RUNNR
Data type: PIC 9(8) COMP-4
RunID of the script - UC-RETURN-CODE
Data type: PIC 9(8) COMP-4
Return code of script execution - UC-MESSAGE-TEXT
Data type: PIC X(256)
Variable message part that explains the value of the return code - UC-PRT-INI
Data type: PIC S9(8)
For internal CallAPI processing only - UC-HND-LOG
Data type: PIC S9(8)
For internal CallAPI processing only - UC-HND-TRC
Data type: PIC S9(8)
For internal CallAPI processing only - UC-HND-HLP
Data type: PIC S9(8)
For internal CallAPI processing only - UC-POINTER
Data type: PIC S9(8
For internal CallAPI processing only - FILLER
Data type: PIC X(12)
Not used - UC-INIFILE
Data type: PIC X(45)
Path and name of INI file
Allowed values:
The error code in cErrorCode is automatically set and can contain one of the following values:
Depending on the specified value, this flag results in one of the following processing options:
CallAPI with Java
This requires the class UCCALL3 to be imported from the package com.uc4.uccall3.
The delivery directory contains sample programs that show you how to log on, activate scripts, connect to different systems, find connections error, and so on. The supplied CallAPI documentation provides up-to-date information about the Java class, methods and available functions.
CallAPI with Visual Basic
This function is found in the COM object AE.Call3 which must be registered.
Example
regsvr32 c:\AUTOMIC\callapi\windows\bin\ucxbwi3c.dll
The delivery directory contains a sample program that provides a detailed description of how you can activate a script.
Methods
In your program, you can use the following functions. They supply return code 0 if the action was successful, or a message number if an error has occurred.
- Logon client, user, [department, [password]]
Use it to log in to the AE system - SetIniFile path and name of INI file
Specifies the INI file - LogonAsDefault
Logs on by using the data that is specified in the INI file - ActivateScript script
Activates a script - Logoff
Use it to log off from the AE system
Attributes
Information about script execution is automatically stored in the following script variables:
- lRunNr
RunID of the script
Data type: Long - lRetCode
Return code of the script execution
Data type: Long - cRetText
Variable message part which explains the return code value
Data type: String
Examples are supplied as part of the delivery package for all supported platforms.
Use the CallAPI Utility (ucxbxxxc)
You can use a CallAPI utility which is provided for each supported platform. You do not need to have any programming knowledge. Depending on your operating system, you can call this utility from jobs, procedures, executable files or directly from the command line.
Write the script that you want to use in a text file and assign this file when you call the utility. The following syntax applies to all platforms:
CallAPI file SCRIPT=script file [LOGON=client,user,[department[,password]]] [INI=INI file] [QUEUE=Name of Queue object]
Parameters:
- SCRIPT=
Path and name of the text file that contains the script - (Optional) LOGON=
Automation Engine login information that is composed of client, user, department and password.
Note: Single Sign-On is used if no user name is provided - (Optional) INI=
Path and name of the INI file that should be used
Note: You must specify this parameter when the INI file has been renamed or moved - (Optional) QUEUE=
No default parameter
Defines the Queue in which the script should run, see Queues (QUEUE). - (Optional for z/OS) REMOTEID=
No default parameter
Defines the identification that the CallAPI uses to log on.
For details, see Connections
(Windows) Example
UCXBXXXC SCRIPT=C:\AUTOMIC\CallAPI\script.txt LOGON=98,SMITH,PASSWORD INI=C:\AUTOMIC\CallAPI\WINDOWS\ucxbxxxc.ini
Notes:
- LOGON parameter is not defined: The login information is retrieved from the INI file, you can successfully log on.
- LOGON parameter is defined, (optionally the department), but no password: A logon error will occur, and access is denied.
The CallAPI utility supplies several return codes that can be used to monitor script activation:
- 0
AE Script was activated without an error.
Note: There are errors that cause an output in the Messages pane of the Automic Web Interface and/or the report but they do not cause the AE Script to abort. This can happen if the commands ACTIVATE_UC_OBJECT and IMPORT include errors. The CallAPI utility always ends with the return code 0 in such a case. - 4
AE Script was activated, but then terminated with the script statement :STOP MSG, 50, "Any text." - 8
Error when activating script or the AE Script was terminated with the script statement :STOP MSG, 51 - 59, "Any text." or :STOP, NOMSG
Note: Return code 8 is displayed if the activation of AE Script has been canceled because of an error, and cannot be continued. This can happen if a script element is not spelled correctly, or if an incorrect number of function parameters is specified. - 12
Error during logon/execution.
Note: Return code 12 can refer to any fatal error that occurred during logon or the execution of the CallAPI script. You need to solve these causes manually. - 16
Fatal error: The script file could not be opened or read.
(SAP) The start parameter for the RFC Server is different. -I is the only parameter and it specifies the path to the INI file:
- (Windows) Example
UCXBRXXC -IC:\AUTOMIC\CallAPI\SAP\UCXSAPC.INI
- (UNIX) Example
nohup ./ucxsapc -I./ucxsapc.ini
Tip: Use the Including or Excluding Deactivated Tasks checkbox to search for your script and specify the task type CallAPI, or enter the Task RunID of the CallAPI script.
Platforms for CallAPIs
See also: