
	Version 4.5.2	SEARCH CONTENTS \| PDF PAGE PDF BOOKS \| HOME UP PREV NEXT

— Terminal Emulation —

Procedure Files

This document describes how to work with procedure files.

What is a Procedure File?
Executing a Procedure File
External Parameters
Addressing a Host Session from a Procedure File
Aborting or Terminating a Procedure File
Creating a Procedure File Using Learn Mode
Debugging a Procedure File
Conventions
Command Categories
Variables in Procedure Files

What is a Procedure File?

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.

Example - logging on to a VM mainframe system:

: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).

Executing a Procedure File

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.
Insert the EXECUTE command at the appropriate location:
```
EXECUTE filename
```
Save your modifications.
Execute the modified procedure file.

External Parameters

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.

Example:

The following command executes the procedure file MYPROG with the parameters 1234, abc and AbC:

MYPROG 1234 abc 'AbC'

See also: Task Parameters in the Overview of Object Properties.

Addressing a Host Session from a Procedure File

A host session can be addressed from a procedure file in the following ways:

Explicitly connect to a specific host session
Use the CONNECT command:
```
CONNECT sessionname
```
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, TYPE and IF *SCREEN.

Aborting or Terminating a Procedure File

The execution of a procedure files is aborted or terminated in the following cases:

When you choose the Cancel button 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 the EXIT or CANCEL command is issued from within the procedure file.
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 the Utilities menu, choose Cancel Procedure.

Or:
Choose the following toolbar button:

Creating a Procedure File Using Learn Mode

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.

Caution:
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.
Choose the OK button.

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).

Debugging a Procedure File

When debugging a procedure file, the following additional elements are shown in the terminal application window:

The Debug menu. 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+R	Run Procedure.
	CTRL+SHIFT+S	Step Procedure.
	CTRL+SHIFT+A	Animate Procedure.
	CTRL+SHIFT+P	Toggle Breakpoint.
	CTRL+SHIFT+B	Break Procedure.
	CTRL+SHIFT+E	Set Echo Time. The 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 `ECHO`.
	CTRL+SHIFT+T	Terminate Debug.

To debug a procedure file

From the Utilities menu, choose Task List.

The Select Task or Procedure dialog box appears.
Select the Procedures option button.
Select the procedure to be debugged.
Choose the Debug button.
Use the Debug menu or debug toolbar to debug the procedure file.
When debugging has been completed, terminate the debug session using the corresponding command.

Conventions

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 IF, IFNOT und WAITFOR.
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:

Command String
Tag
Comment
Blank Line

Command String

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).

Tag

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

$TIMEOUT and $ESC are tags with specific meanings (see below).

`$TIMEOUT`

When the $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 RESPONSE 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`

When the $ESC tag is used in a procedure file and the user chooses Cancel Procedure from the Utilities menu (or the corresponding toolbar button), control is automatically passed to the statement that follows the tag.

If the $ESC tag is not used in a procedure file and the user chooses the Cancel Procedure 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 Cancel Procedure command, control is passed to the $ESC tag.

Comment

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

Blank Line

You can use blank lines anywhere within a procedure file. Entire Connection ignores them.

Command Categories

The commands that can be used in a procedure file can be divided into the following categories:

Host Communication
Processing
Input/Output
Task Management
Operating System Functions
Environment Control

Host Communication

Using the following commands, you can maintain host sessions from within a procedure file:

Command	Description
`CONNECT`	Open a host session.
`DISCONNECT`	Close a host session.
`EMULATE`	Switch to terminal emulation mode.
`QA`	Record sessions, terminal emulation screens and user input in Entire Test Client format to disk.
`REC_BUFF`	Record data untranslated from the terminal emulation buffer to disk.
`REC_SCR`	Record terminal emulation screens to disk.
`REC_XFER`	Record data transfer buffers to disk.
`REVEAL`	Display the field attributes of the 3270 emulation and the value of the ASCII character at the current cursor position.
`RSPMONITOR`	Switch the response time monitor for terminal emulation on and off.
`SUSPEND`	Deactivate the current host session.
`TYPE`	Send simulated keyboard input to the host or PC.

Important:
The REC_BUFF and REC_XFER commands are used for Entire Connection problem resolution and should only be used with the assistance and direction of your technical support.

Processing

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.

Command	Description
`DECR`	Subtract 1 from the global and local counter variables or screen position variables.
`ELAPSETIME`	Calculate the difference, in seconds, between two date and time stamps.
`EXIT`	Leave a procedure file and return to the previous procedure file or to Entire Connection.
`GOTO`	Branch to another location in the procedure file.
`IF`/`IFNOT`	Check a condition.
`INCR`	Add 1 to the global and local variable counters or screen position variables.
`INPUT`	Prompt the user for input.
`LEARN`	Create a procedure file in learn mode.
`PAUSE`	Suspend processing for a specific period of time.
`PERFORM`	Branch to another location in the procedure file and execute the statements defined at this location.
`RESET`	Reset a local or global variable to zero or blank.
`RETURN`	Continue processing with the statement that occurs directly after the `PERFORM` command.
`SET`	Assign a value to a local, global, or system variable.
`SHIFT`	Shift the contents of the global or local parameter variables `PARM2` through `PARM9` down into `PARM1` through `PARM8` in order to set `PARM9` to a null value.
`SLEEP`	Suspend procedure file processing for a specific period of time.
`TOGGLE`	Toggle between two possible states of a system variable.
`WAIT`	Suspend processing of a procedure file until the user presses a key.
`WAITFOR`	Check a condition on the next terminal emulation screen that will be sent by the host.
`WAITM`	Suspend processing of a procedure file for a specific period of time.
`WAITUNTIL`	Suspend processing of a procedure file until a specific date and time.

Input/Output

Using the following commands, you can read files and write data to files.

Command	Description
`CLOSE`	Close a file.
`OPEN-I`	Open a file from which data are read (input file).
`OPEN-O`	Open a file into which data are written (output file).
`READ`	Read data from an input file.
`WRITE`	Write data to an output file.

Task Management

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.

Command	Description
`EXECTASK`	Execute an Entire Connection task.
`EXECUTE`	Execute a procedure file.
`SCHEDTOP`	Schedule further tasks or procedure files on a first-in-first-out (FIFO) basis.
`SCHEDULE`	Schedule further tasks or procedure files on a last-in-first-out (LIFO) basis.

Operating System Functions

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.

Command	Description
`CD`	Change the current directory on the current drive.
`CHDRIVE`	Change the current drive.
`CHMOD`	Change the file attributes.
`DOS`	Execute a DOS command.
`DOSDIR`	Display directory information.
`ERASE`	Erase a file.
`MD`	Make a directory.
`OS`	Same as the DOS command.
`POPDIR`	Return to the position in the directory hierarchy that was saved using the `PUSHDIR` command.
`PUSHDIR`	Save the current position in the directory hierarchy.
`RD`	Remove a directory.
`RENAME`	Rename or move a file.

Environment Control

The following commands are available from within a procedure file:

Command	Description
`BEEP`	Sound the PC alarm.
`CANCEL`	Abort processing of a procedure file.
`LOG`	Write a message to the log file.
`MSG`	Display a message.
`QUIT`	Close an Entire Connection terminal.

Variables in Procedure Files

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.

SEARCH CONTENTS | PDF PAGE PDF BOOKS | HOME UP PREV NEXT