PH-START

Starts a Terminal Independent Process Handler (TIPH) process.

Syntax

PH-START

Prompts

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

* This prompt only displays if you specify U at the Enter options? prompt.

Parameters

Options

H Hushes the PH-START message.

L Suppress the running of the Account Logon Program, 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.

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 after the TIPH process is finished.

T Assumes that a Terminal is associated with the TIPH process. No hold file is created.

U Allows you to specify a different User-id and password (if any) than the one you are logged on to.

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

HP Hushes the PH-START message and prints the hold file after the TIPH process is finished.

HN Hushes the PH-START message but does not create a hold file. All terminal output is lost.

HT Hushes the PH-START message and outputs to the terminal.

M Enables a monitoring tag in TIPH output — required to work on Microsoft Windows.

Unix uses named streams for the input and output making it easy to identify them by process. However, Windows uses random file names in the database's tmp folder. These files are also locked from viewing. The solution is to use the M option to add a tag to the output so each file can be copied (using XCOPY) and then checked for the presence of this tag.

Naming a TIPH task

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

The task-id is not the same as the item-id in the PH-HISTORY file for a particular task.

The H option

The H option is useful when an applications program starts a TIPH process because it prevents a message being displayed on the user's screen.

The P option

The P option does not delete the Spooler hold file.

You must delete the hold file by selecting SP-JOBS Action Code 5. or by typing the Spooler command SP-DELETE at TCL. Refer to SP-JOBS and Related Procedures for more information.

Entering the command stream

Any TCL command except LOGTO can be entered in a TIPH command-stream. 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.

Each line of data, and a carriage return, are supplied as input to the program. This means that if an INPUT statement specifies a maximum length, any unread characters, including the carriage return, will be read by subsequent input statement(s).

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

1. At the TCL prompt, enter

   PH-START

2. 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.
3. 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.
4. 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.

5. At the Enter TIPH user id and password?  prompt, enter the user-id and password (if any) separated by a comma.
6. At the Enter account for TIPH job? prompt, enter the name of the account in which the TIPH command stream is to be executed.
7. 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.

8. At the prompt,

   Enter command stream <CR to end>
   Use '<' for a null line
   >

   type the TIPH command-stream you want to process, as described above. 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 letting you know whether or not the specified task has started successfully.

[1000] TIPH JOB STARTED ON ACCOUNT '~' USING PORT ~

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

If you specify a port number that is not allocated as a TIPH port, the following message displays:

Port n is not a TIPH port

If you specify a port number that is not available, the following message displays:

[924] Port not available.

If you specify a port number to which another user or a TIPH process is already logged on, the following message displays:

Port already logged on

If you specify an invalid user-id and password or account name and password, the following message is displayed after you finish typing the command stream:

[928] Invalid logon attempt.

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