CallAPI

CallAPIs are used to trigger processes in an AE system from external systems by using the Automation Engine scripting language. Use CallAPIs to start executable objects, set or read the contents of Variable objects, or get status details about tasks. As an administrator, you set up the CallAPI and you define the login credentials, the connection data to the AE, and your platform-specific parameters. You can use the CallAPI either with your own program, or with a utility. A CallAPI is limited to 32000 characters, as are all scripts in the Automation Engine scripting language.

Tip: Consider using the REST API instead of the CallAPI in some cases. The REST API has a /scripts endpoint that covers Call API functions. The advantages are that you do not need to use several Service Manager services if you are connecting your own system(s) to several AE systems and/or clients. Also, the REST API does not require a user login whenever it is called. This is very helpful in situations where the workload is high. For more information, see REST API

General Information

Log in to the AE system

To log in to the AE system, the CallAPI requires 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 this information.

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 script statement :STOP 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:

1. Log in to the AE system.
2. Transfer the script to the AE system.
3. 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 with C or C++. The file uccall3.h provides information about structure and functions.

You need to integrate the files uccall3.h and the respective library for your platform. Note that your program requires access to the required libraries such as ucxbwi3c.dll (Windows), or libucxblx6c.so (Linux) etc.

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*
  Data type of return code: long

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

• UCCALL3_ActivateScript (structure, script)
  Use it to activate a script
  Data type of structure: UCCALL_PARAMS*
  Data type of script: char*
  Data type of return code: long
  
• UCCALL3_Logoff (structure)
  Use it to log off from the AE system
  Data type of structure: UCCALL_PARAMS*
  Data type of return code: long
• 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*
  Data type of return code: long

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.

Allowed values:

• 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

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 the AE system to respond
• cLanguage
  Data type: char
  Language in which messages are written
• cFlag1
  Data type: unsigned char

Depending on the specified value, this flag results in one of the following processing options:

• CALL_FLAG1_INI_SERVER
  The connection to the communication process is retrieved from the INI file.
• CALL_FLAG1_INI_LOGIN
  Login data is retrieved from the INI file.
• CALL_FLAG1_INI_USEMSL
  This option converts variable message parts to a complete message text.
• CALL_FLAG1_INI_USEALL
  The settings that are defined 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

CallAPI with Cobol

You can 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 USINGstructure, 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 theAE 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.

Allowed values:

• OPC_LOGON
  Logs on to the AE system
• OPC_LOGOFF
  Logs off from the AE system
• OPC_ACTIVATE_SCRIPT
  Activates a script
• UC-ERROR-CODE
  Data type: PIC X

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
• 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)
  The 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 the AE system to respond.
• UC-LANGUAGE
  Data type: PIC X
  Language in which messages are written
• FILLER
  Data type:PIC X(2)
  Not used
• UC-FLAG1
  Data type:PIC X

Depending on the specified value, this flag results in one of the following processing options:

• CALL_FLAG1_INI_SERVER
  The connection to the communication process is retrieved from the INI file.
• CALL_FLAG1_INI_LOGIN
  Login data is retrieved from the INI file
• CALL_FLAG1_INI_USEMSL
  This option converts variable message parts to a complete message text.
• CALL_FLAG1_INI_USEALL
  The settings that are defined 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

CallAPI with Java

To use the CallAPI with Java, you must import the UCCALL3 class to be imported from the com.uc4.uccall3 package.

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

To use the CallAPI with your own Visual Basic programs, you must register the COM object AE.Call3.

Example

regsvr32 c:\AUTOMIC\callapi\windows\bin\ucxbwi3c.dll

Use the sample program that is included in our delivery directory. It provides a detailed description of how you can activate a script.

Methods

In your program, you can use the following functions. These functions 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
• SetIniFilepath and name of INI file
  Specifies the INI file
• LogonAsDefault
  Logs on by using the data that is specified in the INI file
• ActivateScriptscript
  Activates a script
• Logoff
  Use it to log off from theAEsystem

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
  

Use the CallAPI Utility (ucxbxxxc)

You can use a CallAPI utility which is provided for each supported platform. No programming knowledge is required for this purpose. 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 Queue (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 the script activation process:

• 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

Scripts that are started through a CallAPI are displayed in the Process Monitoring perspective. A statistical record and a report are created.

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

• CallAPI for BS2000
• CallAPI for Java
• CallAPI for NSK
• CallAPI for OS/400
• CallAPI for SAP
• CallAPI for UNIX
• CallAPI for VMS
• CallAPI for Windows
• CallAPI for z/OS

See also:

• :PUT_READ_BUFFER, :PUT_PROMPT_BUFFER to store values for an activated object