Office of Information Services - Application Programming

SETPTR Controls

Description

This application uses a series of programs and a primary controlling file to give easy selection of output destination.

Primary Controlling File(s)

Program Names

*Cataloged programs

OS.LIB *SETPTR.CONTROL.MAIN

This program is the main controlling program for the application. It is the program which should, generally, be called from the controlling program.

OS.LIB *SETPTR.CONTROL.MAIL

This program controls controls the setptr command for sending output to an email address. Unless SP$INVALID.PRINTERS or SP$APPL.PRINTERS further eliminates specific formatting (tab versus ASCII - see SP$PRINTER.ID "email" below), the user will be asked if they want the email record to be in tab delimited format or ascii format. SP$PRINTER.ID is then set to email.tab or email.ascii. The program request subject and email address input. Address are downcased. If the entered address has to "@" in it, "@pittstate.edu" is defaulted. When able to execute the necessary SETPTR, SP$VALID.SET is set to @TRUE (1), and control is returned.

OS.LIB *SETPTR.CONTROL.TRANSMIT

This program controls the setptr command for sending output to the current account's &HOLD& file for later downloading. The id of the HOLD file record will be the login number, as determined by OS.LIB *GET.LOGNUM. If the user is not familiar with the &HOLD&, is very familiar with downloading from the TRANSMIT file, and / or it is desirable to provide consistency by having the downloading occur from the TRANSMIT file, OS.LIB *MOVE.HOLD.FILE or OS.LIB *MOVE.HOLD.FILE.INIT can be used after the report is produced to move the output to the TRANSMIT file, and delete it from the &HOLD& file. This program returns the value "transmit.tab" or "transmit.ascii" in the variable SP$PRINTER.ID to the controlling program so that the controlling program knows the desired format, tab delimited or ASCII, for the output. If the output is only available in ASCII formt, SP$INVALID.PRINTERS should be set to "transmit.tab", and vice versa. See SP$APPL.PRINTERS for another way to control whether tab/ascii format is allowed. When able to execute the necessary SETPTR, SP$VALID.SET is set to @TRUE (1), and control is returned.

OS.LIB *SETPTR.CONTROL.SAVE

This program puts the current SETPTR settings, using !GETPU, into the variable SP$PRINTER.SETTINGS prior to the SETPTR in the application being executed. This, in effect, savings the settings so that, using OSL.LIB *SETPTR.CONTROL.RESET, they can be restored following the output production.

OS.LIB *SETPTR.CONTROL.RESET

This program uses the settings in the variable SP$PRINTER.SETTINGS which were stored during the OS.LIB *SETPTR.CONTROL.SAVE program to reset the SETPTR to the state it was in prior to the execution of the most recent SETPTR. It uses !SETPU to accomplish this. If able to accomplish the reset, SP$VALID.SET is returned with a value of @TRUE (1).

OS.LIB *SETPTR.CONTROL.GETID

This program is used when SP$PRINTER.ID is NULL. It attempts to read the login number record from LPD.USER.CONTROL. If it cannot, an error code of 1 is returned. If so, it compares SP$INVALID.PRINTERS to the printer list in the record. Any matches are removed from the valid printer list. If SP$APPL.PRINTERS is not NULL, it compares printer list to SP$APPL.PRINTERS and eliminates and matches not found. If there are no valid printers at this point, SP$PRINTER.ERROR is set to 2 and control is returned. If there is one printer, SP$PRINTER.ID is set to this printer, and control is returned. If there is more than 1 printer, *DISPLAY.SCREEN is called to allow the user to select the desired output destination, SP$PRINTER.ID is set to this printer, and control is returned.

OS.LIB *SETPTR.CONTROL.EXECUTE

This program reads the printer record for the value of SP$PRINTER.ID. If it cannot, SP$PRINTER.ERROR is set to 3, and control returns. The calling program should then decide whether to continue processing / printing. If the desired SETPTR is executed, SP$VALID.SET is set to @TRUE.

OS.LIB *SETPTR.CONTROL.ACCT

This program attempts to SETPTR based on the account's VOC SET.PTR record.

OS.LIB *SETPTR.CONTROL.DFLT

This program is called as a result of the SP$PRINTER.ID being set to "dflt" . It attempts to do a SETPTR based on a "lognum.dflt" record in the LPD.USER.CONTROL file. This is a situation (having a personal setptr) which should be avoided if possible. Users should be encouraged to accept the VOC SET.PTR whenever possible. If, however, a personal setptr is really necessary, the program allows that to happen.

OS.LIB SETPTR.CONTROL.INIT

This program can be used prior to OS.LIB *SETPTR.CONTROL.MAIN to open files and set variables when there is not controlling program available, for example, when the application needs to be run directly from a VOC/VOCLIB.

OS.LIB SETPTR.CONTROL.COMMON

This is not actually a program, but a record which lists the common variable used in this application. The comment section at the beginning of the program lists all programs using this variable.

Primary Variables (passed via COMMON statement)

SP$PRINTER.ID

Controlling program should set to one of the following:

SP$PRINTER.ERROR

When entering the application, this variable should be set to NULL ("") or @FALSE (0). If an error condition is found during processing one of the following error codes will be returned. The calling program should decide whether to continue to allow printing / processing to occur if an error condition is returned

SP$USER.ERROR

When entering the application this variable should be set as follows:

SP$PRINTER.SETTINGS

Dynamic array which is used to hold the current printer settings before a new SETPTR is executed in the SET.PRINTER.EXECUTE subroutine. These settings can then be reset by calling SETPTR.CONTROL.RESET. The controlling program should set to NULL initially, but should not reset to NULL after once entering the application, as RESET function will then be effectively eliminated.

SP$INVALID.PRINTERS

This is a multivalued variable set by the controlling program and used to disallow any potential printer selections that a person may have from the list of printers in the user record. An example would be, this report should not be sent to the sys_laser. SP$INVALID.PRINTERS should be set to sys_laser in the controlling program. Another example, the program or VOC creates an ASCII report, but not a tab delimited one. SP$INVALID.PRINTERS should be set to transmit.tab.

SP$VALID.SET

Initially set to NULL or @FALSE (0) in the controlling program, this variable will return an @TRUE (1) if a successful SETPTR was executed.

SP$SETTINGS.ERROR Variable which hold the results of !GETPU in the .SAVE program or !SETPU in the .RESET program.

SP$APPL.PRINTERS This variable provides another way of controlling, from the application, the output destinations allowed. Whereas SP$INVALID.PRINTERS eliminates certain choices, SP$APPL.PRINTERS can be used to only allow certain choices. For example, if output from an application should only be sent to a specific printer, rather than setting SP$INVALID.PRINTERS to all the possible printers you don't want, SP$APPL.PRINTERS can be set to the only one that you do want.

Setting up a new user in the LPD.USER.CONTROL file

Use the following (see 0133577 for example):

  1. Record id is the user's people id - the value of LOGNUM in *CALL GET.LOGNUM(LOGNUM)
  2. Field 1 should be the printer of last resort if SP$PRINTER.ID is set to "dflt" at entry time (see "dflt" above). If you aren't sure what print this should be, check for a SET.PTR record in the account VOC, or as the user where they would normally like to have the majority of their output sent.
  3. List any other printers that the person may want to use. Remember, these printers must also be in the LPD.USER.CONTROL file.

Setting up a new printer in the LPD.PRINTER.CONTROL file

  1. Record id should be the printer name as it is in users' records. See sys, russ, ksanley as an example. For an LPD printer is should always be the computer/printer name as defined in the AT portion of the SETPTR, minus the -pc.pittstate.edu part. System printers should be their assigned spoolq name.
  2. Field 1 is the actual SETPTR command that will be executed.
  3. Field 2 is a "Y" if a "BANNER account.name" needs to be added to the SETPTR command (see sys and russ versus ksanley).
  4. Field 3 should be a short description of the printer. When entering this, remember that printers get moved around a lot. A description of "In the south corner on the old gray desk" doesn't help much when it gets moved to the north corner and put on a blue desk.

Other issues