PH-START

Starts a Terminal Independent Process Handler (TIPH) process.

Syntax

PH-START

Prompts

Enter taskid for TIPH task? {taskId}
Enter port number for TIPH task? {portNumber}
Enter options? {options}
Enter TIPH user id and password? userId{,password} *
Enter account for IPH job? accountName
Enter account password? {accountPassword}
Enter command stream <CR to end>
Use '<' for a null line
> commandStream

* This prompt is only displayed if you have specified the U option.

Parameters

taskId The name of the TIPH process. This name is recorded in the PH-HISTORY file. If you do not specify a task name, the literal 'None' is used.

portNumber The number of a port allocated for use by a TIPH process. If you do not specify a port number, the next available port is used, starting with the highest number.

Note: If the specified port is the base of a range defined in the devices file using the OPEN and RANGE keywords, PH-START will use the next free port in the range.

options One or more option as letters listed in Options below.

userId{,password}
The user-id under which to run the TIPH. The default, if not specified, is the current user-id. If the user-id requires a password, this must be separated from the user-id with a comma.

Note: Your administrator can set an SSM Security Profile option so that you do not need to supply a password when running a TIPH.

This prompt is only displayed if you have specified the U option.

accountName The name of the account in which the TIPH command stream is to be executed. The account name is required. You can use any allowable account name that is specified in the user's security profile.

accountPassword
The account password (if any) for the account name specified at the previous prompt.

commandStream A list of TCL commands, Proc names, or whatever input the TIPH process needs to do its work.

Options

H Suppresses the PH-START message.

This option is useful when starting a TIPH process from an applications program, because it prevents a message being displayed on the user's screen.

L Suppress the running of the logon Proc, unless an ‘R’ is specified in attribute 9 of the account definition item. You can combine this option with other PH-START options.

To use this option, you must first set the SkipLogonProc database configuration parameter.

U Allows you to specify a different user-id and password (if any).

Use this option if you want to run a TIPH process on an account that is not allowed logon by the user-id you are currently using.

Hold File Options

These options allow you to choose how to process the output of a TIPH process (that is, all output that is normally displayed on a terminal, including log on, log off, and system messages).

N No logging. No hold file is created and all terminal output is lost.

P Prints the hold file on the printer assigned to your process when the TIPH process is finished.

Note that the P option does not delete the Spooler hold file. This can be done with SP-JOBS Action Code 5 or the SP-DELETE command.

T If a terminal is connected to the TIPH port, sends the output to that terminal. No hold file is created.

If none of these options are specified, a Spooler hold file is created and output is suppressed.

Note: These options cannot be combined.

Task Name

It is a good idea to give a TIPH task a name that helps you identify the process. This name is recorded in the PH-HISTORY file.

Note: The task name (task-id) is not the same as the item-id of the task in the PH-HISTORY file.

Entering the Command Stream

Any TCL command except LOGTO can be entered in a TIPH command stream (commandStream in Parameters). Each command must be typed on a separate line by pressing RETURN between commands.

If the operation to be performed by the TIPH process requires operator input, such as a DataBasic program with INPUT statements, include the input as part of the command stream. You must type each value on a separate line, separated by pressing RETURN.

PH-START always stacks the command 'OFF' as the last line in the command stream.

Because you have to press RETURN to end a command stream, you cannot reply to a program prompt by pressing RETURN. If your program requires a RETURN, type a less-than character (<) in the command stream to indicate the RETURN.

It may be more efficient to write a Proc that contains your commands, and then to call that Proc in your command stream, rather than placing the commands themselves in the command stream. However, if the input to the TIPH job varies each time you run the job, this technique is not useful.

If a Proc is written to drive the PH-START command, the method for stacking a null line in the command stream is to use H<<<. This is because a single less-than character (<) indicates a RETURN in the Proc secondary output buffer and double less-than characters (<<) indicate continuation on the next line.

Procedure

At the TCL prompt, enter
```
PH-START
```
At the Enter taskid for TIPH task?, prompt, enter a name to identify the TIPH task, or press RETURN only to accept the literal None as the task-id.
At the Enter port number for TIPH task prompt, enter a port number allocated for TIPH use, or press RETURN only to accept the next available process number. If you press RETURN the software allocates a Reality process number to run the TIPH, but you have no terminal access.
At the Enter options? prompt, enter the option(s) required, or press RETURN only if no options are required.

The following prompt (step 5) only displays if you specify U at the Enter options? prompt.

At the Enter TIPH user id and password? prompt, enter the user-id and password (if any) separated by a comma.
At the Enter account for TIPH job? prompt, enter the name of the account in which the TIPH command stream is to be executed.
At the Enter account password? prompt enter the password of the account named at the previous prompt. If no password is required, press RETURN only.
At the prompt,
```
Enter command stream <CR to end>
Use '<' for a null line
>
```
type the TIPH command stream you want to process. For more information on entering the command stream, refer to Entering the Command Stream. To end the command stream, press RETURN only at the > prompt.

After you type the command stream and press RETURN, the following message is displayed to tell you that the specified task has started successfully.

[1000] TIPH JOB STARTED ON ACCOUNT 'accountName' USING PORT portNumber

The responses to each prompt are not validated until you finish typing all the information.

If you type an invalid response at any of the PH-START prompts, a message is displayed telling you what is wrong. You must then repeat the entire procedure.

Error Messages

Port portNumber is not a TIPH port

The port you have specified is not allocated as a TIPH port:

Note: If you are using a range of TIPH ports (configured in the devices file using the RANGE keyword), this may indicate that you have not specified the base port of the range.
[924] Port not available.
The port you have specified is already in use. If you are using a range of TIPH ports, all the ports are in use.
[928] Invalid logon attempt.
You have specified an invalid user-id and/or password or account name and/or password.

Example 1

This example starts the TIPH process named TEST.

:PH-START
Enter taskid for TIPH task? TEST
Enter port number for TIPH task? 4
Enter options? return
Enter account for TIPH job? INV
Enter account password? HO
Enter command stream <CR to end>
Use '<' for a null line
>SP-ASSIGN HS 
>SORT INVENTORY (P)
>RETURN
[1000] TIPH job started on account 'INV' using port 4

Example 2

This example starts the TIPH process named TEST1.

:PH-START
Enter taskid for TIPH task? TEST1
Enter port number for TIPH task? 30
Enter options? U
Enter TIPH user id and password? AP,CHECK
Enter account for TIPH job? PAYROLL
Enter account password? CK
Enter command stream <CR to end>
Use '<<' for a null line
>SP-ASSIGN HS
>LIST PAYROLL (P)
>RETURN
[1000] TIPH job started on account 'INV' using port 30