6 Handling GSOCC Messages

These are handled by DTASK_GSOC() in the first instance. In addition to the transaction identification, PATH and MESSID, the CONTEXT, NAME and VALUE components of the received message are passed.

Firstly the PATH and MESSID from the message are set for SUBPAR (SUBPAR_PUTPATH()) in case it wants to reply with a message or request a parameter value as a result of this message, then a DTASK routine appropriate to the CONTEXT is called.

When the required action for the CONTEXT is complete, the transaction is ended by calling (DTASK_COMSHUT()) which flushes any error messages on the stack to the master task (using ERR_CLEAR()) before sending a final acknowledgment. (The master task must therefore be prepared to handle any MESSYS__INFORM messages prior to the final acknowledgement in any CONTEXT.) The final acknowledgement will have an appropriate message status and the message value will depend upon the status and the CONTEXT.

6.1 GET Context

GET is handled by DTASK_GET(). NAME contains the name of the required parameter. If the task is a monolith, the parameter name must be of the form ACTION:PARNAME to specify the particular action within the monolith.

The value of the named parameter is obtained, by searching the vpath if the parameter is not already active.

Note that there are some restrictions on the vpath search:

• Dynamic will usually have no effect because any dynamic defaults will be cancelled initially and if the parameter was reset.
• Prompting is disabled so any attempt to prompt will return status PAR__NOUSR.

The transaction is then closed (DTASK_COMSHUT()). Assuming the status is SAI__OK, the message value of the final acknowledgement is the parameter value as a character string. In the event of an error, error messages are reported and the message status set appropriately.

6.2 SET Context

SET is handled by DTASK_SET(). NAME contains the name of the required parameter as for GET. VALUE is a character string which the parameter subsystem can resolve into a value for the specified parameter. The given value is put into the parameter’s internal storage and the parameter is made active (SUBPAR_CMDPAR()). The transaction is then closed (DTASK_COMSHUT()). If an error occurred, error messages will be reported and an appropriate status set in the final acknowledgement.

6.3 OBEY and CANCEL Context

OBEY and CANCEL are further checked in DTASK_GSOC().

NAME contains the name of the required action (or task within a monolith) and VALUE is a string specifying parameter values in a format acceptable to the parameter system.

For OBEY the action must not be active and for CANCEL the action must be active; otherwise the transaction is terminated (in DTASK_COMSHUT()) by calling AMS_REPLY() with a suitable bad message status.

If the OBEY/CANCEL is valid, SUBPAR_FINDACT() is called to set up the parameter system for the specified action and the VALUE string is processed (SUBPAR_CMDLINE()) to set the value of any given parameters.

6.3.1 OBEY

The new action is added to the active list and the list of subsidiary tasks for it is cleared. AMS_REPLY() is called with message status DTASK__ACTSTART to send an initial acknowledgement of the OBEY message .

If that fails the action and/or transaction are closed (DTASK_ACTSHUT() or DTASK_COMSHUT()); if it is OK, DTASK_OBEY() is called.

DTASK_OBEY() calls DTASK_APPLIC() with context OBEY and that in turn calls the user’s top-level routine.

On return from DTASK_APPLIC() if STATUS is not SAI__OK, the message status, MESSTATUS, for the final acknowledgement message is set to the bad status value; if STATUS is SAI__OK, the REQUEST returned from the application is checked (DTASK_ACT_SCHED()) to see whether the action is to be terminated or is to be rescheduled. If the user’s code has not changed it, the REQUEST will be ACT__END.

If a reschedule is requested, DTASK_ACT_SCHED() will set it up; otherwise the action is ended and the communications transaction closed by sending a reply to the task which initiated the OBEY. MESSTATUS for the reply depends on the STATUS and REQUEST returned from DTASK_APPLIC().

If a reschedule was not requested, MESSTATUS will depend upon the value of REQUEST as follows:

6.3.2 CANCEL

CANCEL is handled by calling DTASK_CANCEL().

Details of the OBEY transaction which started this action are obtained from the COMMON blocks (DTASK_CMN) then DTASK_APPLIC() is called with context CANCEL and that in turn calls the user’s code. See SUN/134 for examples of how the user’s code might handle a CANCEL

On return from DTASK_APPLIC the status and REQUEST returned from the application are checked (DTASK_ACT_SCHED()) to see whether the action is to be terminated or is to continue rescheduling. In any case, an acknowledgement is sent to the task which requested the CANCEL. If the action has ended, an acknowledgement is also sent to the task which issued the OBEY.

6.4 CONTROL Context

CONTROL is handled by DTASK_CONTROL(). The message name component, passed as ACTION defines the particular control function required, ’DEFAULT’, ’SETENV’ or ’PAR_RESET’. The required action is performed.

If a problem occurs in the process, an appropriate bad status value is set and error report is made.

The transaction is then closed (DTASK_COMSHUT()).

6.4.1 DEFAULT

The message value specifies a new ‘current working directory’ required for the task. If the value is blank, no change is required; otherwise the change is made by calling the appropriate system routine.

Whether or not a change was made, the ‘new’ current working directory is obtained and returned as the message value in final reply message. CONTROL DEFAULT can therefore be used to enquire the task’s current working directory without changing it.

6.4.2 SETENV

The message value specifies a new value for an environment variable for the task. It has the form: ‘VARIABLE = NEWVALUE’, where VARIABLE is the name of the environment variable and NEWVALUE is the required value. The string may be quoted – quotes will be stripped in the usual way. If the string is unquoted, leading blanks will also be stripped from NEWVALUE.

The environment variable is set by calling the appropriate system routine.

6.4.3 PAR_RESET

This causes the task’s parameters to be reset to the ‘ground’ state. The message value may be used to specify the name of an individual task in a monolith; if it doesn’t, parameters for all tasks in the monolith are reset. Resetting is done by calling SUBPAR_DEACT() with argument TTYPE set to ‘R’ – MIN, MAX and dynamic default values are also cancelled but GLOBAL values are not updated.