This document describes how to work with procedure files.
Procedure files (extension ncp) initiate operations which are executed on the host, the PC, or both. You can create procedure files using a PC editor, a host editor or in learn mode.
For example, you can create a procedure file which automates the process of logging on to a host system. All required logon commands are contained in the procedure file and are executed when the procedure file is invoked.
:LOGON TYPE CR IF *SCREEN NE 'CP READ' GOTO ERROR TYPE 'LOGON' *USERID1 CR TYPE *PASSWORD1 CR SET #CNT1 0 :VM IF *SCREEN EQ 'VM/SP RELEASE 4' GOTO NAT INCR #CNT1 IF #CNT1 GT 10 GOTO ERROR PAUSE 200 GOTO VM :NAT TYPE 'NAT' CR GOTO FINI :ERROR MSG 'CANNOT LOGON - TRY LATER' :FINI EXIT
Sample procedure files are copied to your hard disk during installation (if specified).
You can execute a procedure file in the following ways:
Select the procedure file from the task list.
Enter the name of the procedure file and, if applicable, all required parameters in the command line.
Execute a procedure file which invokes another procedure file, see below.
Press the key or key combination that is defined for the procedure file.
To invoke a procedure file from another procedure file
Open the procedure file from which you want to invoke another procedure file.
command at the appropriate location:
Save your modifications.
Execute the modified procedure file.
You can pass up to 9 external parameters to a procedure file. The external parameters can be checked within the procedure file, using the appropriate parameter variables.
The following command executes the procedure file
MYPROG with the parameters
MYPROG 1234 abc 'AbC'
See also: Task Parameters in the Overview of Object Properties.
A host session can be addressed from a procedure file in the following ways:
Explicitly connect to a specific host session
Implicitly connect to the active host session
If you execute a procedure file while a host sessions is open.
Implicitly connect to the default host session
If you execute a procedure file while no host session is open, the default session is automatically opened when the first statement addressing a host session is encountered. The default session is specified in the user properties. Commands that require open sessions are, for example,
The execution of a procedure files is aborted or terminated in the following cases:
When you choose thebutton in a dialog box that was invoked by the procedure file.
When a non-recoverable error occurs during procedure file processing (for example, a syntax or logic error).
When the maximum host response time is exceeded.
When a normal exit from the procedure file occurs (i.e. when the last statement is executed).
You can also abort the currently active procedure file as described below.
To abort the currently active procedure file
From themenu, choose .
Choose the following toolbar button:
In learn mode, all keyboard input entered in a host session is stored in a procedure file. The commands in the procedure file are automatically executed when you execute the procedure file.
For example, you can use learn mode to record all keyboard input required to logon to the host.
Though learn mode creates procedure files that can be executed successfully, they are not robust as long as you do not add error and exception handling.
To invoke learn mode
Open a host session.
Use the key combination CTRL+L to invoke learn mode.
CTRL+L is the default. You can also define another key combination.
The Learn dialog box appears.
Select the desired procedure file from the list box, or specify the name of the (new) procedure file with the extension ncp in the File name text box.
If you specify an existing procedure file, it will be overwritten by the new procedure.
Learn mode is now active and all keyboard input is recorded.
To disable learn mode
Use the key combination CTRL+L (default) to switch off learn mode.
The resulting procedure file contains all of your keyboard input. You can modify this procedure file using an ASCII editor (for example, to include check routines or logical queries).
When debugging a procedure file, the following additional elements are shown in the terminal application window:
Themenu. This menu is only available as long as you debug a procedure file. It provides the same commands as the debug toolbar.
A debug toolbar. This toolbar is only available as long as you debug a procedure file.
You can move it to the application window (e.g. below the menu bar or next to the terminal emulation screen) so that it is no longer shown in a window. To prevent docking, press CTRL while moving the window.
A procedure window on the left. The display starts with the first executable source text line which is indicated by an arrow.
A variable window on the right, providing a list of all variables that are used in the procedure file.
You can modify the size of the individual windows by dragging a window border with the mouse. You can also display these windows as dockable windows.
Using the following commands or buttons in the debug toolbar, you debug the procedure file.
|CTRL+SHIFT+E|| Set Echo Time dialog box appears, in which you can specify
the desired delay in milliseconds before execution of the next statement. See
the system variable
To debug a procedure file
From themenu, choose .
The Select Task or Procedure dialog box appears.
Select the Procedures option button.
Select the procedure to be debugged.
Use themenu or debug toolbar to debug the procedure file.
When debugging has been completed, terminate the debug session using the corresponding command.
The following rules apply:
Each line in a procedure file can consist of up to 127 characters.
A line can contain only one command and related operands.
Exception: the commands
Statements can be indented for readability.
Exception: tags and comment lines must start in the first column.
Elements such as tags and commands are not case-sensitive. Character strings can be case-sensitive.
The limit for the source code is 64 KBytes, including comments. If this size is exceeded, an error message appears and the procedure aborts.
A line can consist of the following:
A character string must be enclosed with quotation marks if case-sensitivity is required or if there are embedded blanks. You can either use apostrophes or double quotation marks, as long as they are paired consistently. For example:
'This string is a valid single quoted string' 'This string is "also" valid' "This string is a valid double quoted string" "This string is 'also' valid" "This string is invalid because the double quotation marks are not paired'
Entire Connection expects character strings to be in the Windows character set (ANSI).
A tag is a branch point within a procedure file. The name of a tag must always begin with a colon and can be up to 127 characters in length. A tag that is not unique results in an error message.
Examples for tags:
:START :LOGON-ERROR :QUIT
$ESC are tags with
specific meanings (see below).
$TIMEOUT tag is used in a procedure file
and a timeout condition occurs (for example, when the host does not respond
within the defined period of time), control is automatically passed to the
statement that follows the tag.
The system variable
defines how long Entire Connection is to wait for a response from the host
before processing is to continue with the next statement after the tag.
$ESC tag is used in a procedure file and
the user chooses from the
menu (or the corresponding toolbar button),
control is automatically passed to the statement that follows the tag.
$ESC tag is not used in a procedure file
and the user chooses the command,
procedure file processing is aborted.
If a procedure file is executing a task that can be aborted, the following applies:
When the task is aborted, control is passed back to the procedure file.
When the user then chooses the
A comment line starts with an asterisk (*) in the first column. For example:
* This is a sample comment line * * The line before this one is also a comment line
A comment can also be inserted after a statement. In this case, it starts with a slash followed by an asterisk (/*). For example:
SET LOGON NO /* this is a comment after a statement :ERROR /* this is a comment after a tag
You can use blank lines anywhere within a procedure file. Entire Connection ignores them.
The commands that can be used in a procedure file can be divided into the following categories:
Using the following commands, you can maintain host sessions from within a procedure file:
||Open a host session.|
||Close a host session.|
||Switch to terminal emulation mode.|
||Record sessions, terminal emulation screens and user input in Entire Test Client format to disk.|
||Record data untranslated from the terminal emulation buffer to disk.|
||Record terminal emulation screens to disk.|
||Record data transfer buffers to disk.|
||Display the field attributes of the 3270 emulation and the value of the ASCII character at the current cursor position.|
||Switch the response time monitor for terminal emulation on and off.|
||Send simulated keyboard input to the host or PC.|
REC_XFER commands are used for Entire Connection
problem resolution and should only be used with the assistance and direction of
your technical support.
Using the following commands, you can determine the processing logic for a procedure file. For example, depending on the data transmitted from the host, you can execute different commands.
||Subtract 1 from the global and local counter variables or screen position variables.|
||Calculate the difference, in seconds, between two date and time stamps.|
||Leave a procedure file and return to the previous procedure file or to Entire Connection.|
||Branch to another location in the procedure file.|
||Check a condition.|
||Add 1 to the global and local variable counters or screen position variables.|
||Prompt the user for input.|
||Create a procedure file in learn mode.|
||Suspend processing for a specific period of time.|
||Branch to another location in the procedure file and execute the statements defined at this location.|
||Reset a local or global variable to zero or blank.|
|| Continue processing with the statement that occurs
directly after the
||Assign a value to a local, global, or system variable.|
|| Shift the contents of the global or local parameter
||Suspend procedure file processing for a specific period of time.|
||Toggle between two possible states of a system variable.|
||Suspend processing of a procedure file until the user presses a key.|
||Check a condition on the next terminal emulation screen that will be sent by the host.|
||Suspend processing of a procedure file for a specific period of time.|
||Suspend processing of a procedure file until a specific date and time.|
Using the following commands, you can read files and write data to files.
||Close a file.|
||Open a file from which data are read (input file).|
||Open a file into which data are written (output file).|
||Read data from an input file.|
||Write data to an output file.|
Using the following commands, you can schedule or execute other procedure files or tasks. You can break down complex operations into more manageable, separate procedure files, or execute a number of operations based upon external variables.
||Execute an Entire Connection task.|
||Execute a procedure file.|
||Schedule further tasks or procedure files on a first-in-first-out (FIFO) basis.|
||Schedule further tasks or procedure files on a last-in-first-out (LIFO) basis.|
Using the following commands, you can invoke operating system functions from within a procedure file.
Example: using a procedure file, you can download data from the host in regular intervals. In order to write this data to a PC file, the procedure file must rename or erase the PC file that was created during the previous download. Otherwise, manual modifications are required prior to each execution of the procedure file.
||Change the current directory on the current drive.|
||Change the current drive.|
||Change the file attributes.|
||Execute a DOS command.|
||Display directory information.|
||Erase a file.|
||Make a directory.|
||Same as the DOS command.|
|| Return to the position in the directory hierarchy
that was saved using the
||Save the current position in the directory hierarchy.|
||Remove a directory.|
||Rename or move a file.|
The following commands are available from within a procedure file:
||Sound the PC alarm.|
||Abort processing of a procedure file.|
||Write a message to the log file.|
||Display a message.|
||Close an Entire Connection terminal.|
Procedure files can contain variables, where the values of the variables are determined either by the user or by the system.
For complex operations that involve nested procedure files, global variables that are accessed from multiple procedure files can be defined. A global variable can, for example, pass a return code from one procedure file to another. This prevents processing of subsequent program steps if a preceding procedure file has not been completed successfully.