System_Shutdown

Purpose

Use System_Shutdown to systematically end all system function.

Input Parameters

input_length

(int4) The total length of all input parameters (after this one).

function_name_length

(int4) Length of function_name – in this case, 15.

function_name

(string,13,char43) The API function name – in this case, 'System_Shutdown'.

authenticated_userid_length

(int4) Length of authenticated_userid.

authenticated_userid

One of the following:

• (string,1-8,char42) The userid under whose authority to perform the function (AF_INET requests).
• (string,0-8,char42) The userid under whose authority to perform the function (AF_IUCV requests).

Note that authenticated_userid is optional for AF_IUCV requests. See Client Authentication for more information.

password_length

(int4) Length of password.

password

One of the following:

• (string,1-200,charNA) The password or passphrase to be used for authentication (AF_INET requests).
• (string,0-200,charNA) The password or passphrase to be used for authentication (AF_IUCV requests).

Note that password is optional for AF_IUCV requests. See Client Authentication for more information.

target_identifier_length

(int4) Length of target_identifier.

target_identifier

(string,1-8,char42) This must match an entry in the authorization file that also contains the authenticated_userid and the function_name (System_Shutdown).

Within=value

(string,0-5,char10) Send a shutdown signal to enabled users and delay the shutdown until either the specified interval (minus the amount of time reserved for a CP shutdown) has elapsed, or until all signaled user machines indicate that they have shut down, whichever occurs first. The interval is specified as a number of seconds in the range of 1-65535. The default is that no Within=value is submitted.

By=value

(string,0-8,char10 plus :) Sends a shutdown signal to enabled users and delay the shutdown until either the designated time of day (minus the amount of time reserved for a CP shutdown) is reached, or until all signaled user machines indicate that they have shut down, whichever occurs first. The time can be specified as hh:mm or hh:mm:ss. The equivalent interval in seconds must be in the range 1-65535. The default is that no By=value is submitted.

Immediate=value

(string,0-11,char36) One of the following:

IMMEDIATE

Shut down the system immediately without sending shutdown signals to enabled users, even if a previous SHUTDOWN command is pending. If a previous SHUTDOWN command is pending, its operands are not used and must be specified with IMMEDIATE on the new command if they are required.

NOIMMEDIATE

Do not issue the SHUTDOWN with the IMMEDIATE option. This is the default.

Reipl=value

(string,0-7,char26) One of the following:

REIPL

Specifies that the system is to be restarted immediately after the SHUTDOWN command completes. This is the default.

NOREIPL

Specifies that the system is not to be restarted immediately after the SHUTDOWN command completes.

Cancel=value

(string,0-8,char26) One of the following:

CANCEL

This causes a scheduled shutdown to be terminated. Any guests that received termination signals when the original SHUTDOWN command was issued continue to process those signals.

NOCANCEL

This does not cause a scheduled shutdown to be terminated. This is the default.

Response 1 -- Immediate Request Verification

request_id

(int4) The identifier of the request.

Response 2 -- Output Parameters

output_length

(int4) The total length of all output parameters (after this one).

request_id

(int4) The identifier of the request (same as returned in immediate request verification above).

return_code

(int4) The return code.

reason_code

(int4) The reason code.

If RC=8 and RS=3002, the following parameters will be returned:

error_data_length

(int4) Length of error_data.

error_data

(string) UNKNOWN_PARAMETER_NAMES=, followed by a blank-delimited list of input parameter names that are not valid, then followed by a null terminator.

If RC=8 and RS=3003, the following parameters will be returned:

error_data_length

(int4) Length of error_data.

error_data

(string) UNKNOWN_PARAMETER_OPERAND=, followed by a blank-delimited list of input parameter operands that are not valid, then followed by a null terminator.

Usage Notes

1. Syntax errors (RC = 24 and RS = pprr) are only applicable to the common input parameters. Syntax checking is not performed on the additional input parameters for this API. If a valid parameter is specified multiple times, the last value specified for that parameter will be used. For more information, see Key-value pair (KVP) input parameters.

Return and Reason Codes