Service Status Data Structure

The NetServiceStatus API uses the following data structure:

 
struct service_status {
   unsigned short svcs_status;
   unsigned long  svcs_code;
   unsigned short svcs_pid;
   unsigned char  svcs_text[STXTLEN+1];
};

where:

svcs_status specifies the status of the service. This field contains a bit-map mask, defined in the SERVICE.H header file as follows: ┌───────┬──────────────────────┬─────────┬─────────────────────────────────────┐
│ BITS │ SYMBOLIC CONSTANT │ BIT │ DESCRIPTION │
│ │ │ MASK │ │
├───────┼──────────────────────┼─────────┼─────────────────────────────────────┤
│ 0-1 │ SERVICE_INSTALL_STATE│ 0x03 │ General status of the service. │
├───────┼──────────────────────┼─────────┼─────────────────────────────────────┤
│ 2-3 │ SERVICE_PAUSE_STATE │ 0x0C │ Paused/active status. │
├───────┼──────────────────────┼─────────┼─────────────────────────────────────┤
│ 4 │ - │ - │ Service can or cannot be installed. │
├───────┼──────────────────────┼─────────┼─────────────────────────────────────┤
│ 5 │ - │ - │ Service can or cannot be paused. │
├───────┼──────────────────────┼─────────┼─────────────────────────────────────┤
│ 6-7 │ - │ - │ Reserved. │
├───────┼──────────────────────┼─────────┼─────────────────────────────────────┤
│ 8-10 │ SERVICE_REDIR_PAUSED │ 0x0700 │ Redirection paused/active. │
├───────┼──────────────────────┼─────────┼─────────────────────────────────────┤
│ 11-15 │ - │ - │ Reserved. │
└───────┴──────────────────────┴─────────┴─────────────────────────────────────┘

Bits 0 and 1 indicate the general status of the service. ┌─────────────────────────────┬───────┬────────────────────────────────────────┐
│ SYMBOLIC CONSTANT │ VALUE │ MEANING │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UNINSTALLED │ 0x00 │ Service stopped. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_INSTALL_PENDING │ 0x01 │ Service start pending. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UNINSTALL_PENDING │ 0x02 │ Service stop pending. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_INSTALLED │ 0x03 │ Service started. │
└─────────────────────────────┴───────┴────────────────────────────────────────┘

The service currently is in one of the following pause states, and bits 2-3 have these values: ┌─────────────────────────────┬───────┬────────────────────────────────────────┐
│ SYMBOLIC CONSTANT │ VALUE │ MEANING │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_ACTIVE │ 0x00 │ Service active. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_CONTINUE_PENDING │ 0x04 │ Service continue pending. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_PAUSE_PENDING │ 0x08 │ Service pause pending. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_PAUSED │ 0x0C │ Service paused. │
└─────────────────────────────┴───────┴────────────────────────────────────────┘

Bit 4 indicates whether the service can be stopped by an application, shown in the following values: ┌─────────────────────────────┬───────┬────────────────────────────────────────┐
│ SYMBOLIC CONSTANT │ VALUE │ MEANING │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_NOT_UNINSTALLABLE │ 0x00 │ Service cannot be stopped. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UNINSTALLABLE │ 0x10 │ Service can be stopped. │
└─────────────────────────────┴───────┴────────────────────────────────────────┘

Bit 5 indicates whether the service can be paused by an application, shown in the following values: ┌─────────────────────────────┬───────┬────────────────────────────────────────┐
│ SYMBOLIC CONSTANT │ VALUE │ MEANING │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_NOT_PAUSABLE │ 0x00 │ Service cannot be paused. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_PAUSABLE │ 0x20 │ Service can be paused. │
└─────────────────────────────┴───────┴────────────────────────────────────────┘

Bits 6 and 7 are reserved, with a value of 0.
Bits 8-10 indicate whether particular tasks within the Requester service have been paused, shown by the following values: ┌─────────────────────────────┬───────┬────────────────────────────────────────┐
│ SYMBOLIC CONSTANT │ VALUE │ MEANING │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_REDIR_DISK_PAUSED │ 0x100 │ Redirector for disks paused. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_REDIR_PRINT_PAUSED │ 0x200 │ Redirector for spooled devices paused. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_REDIR_COMM_PAUSED │ 0x400 │ Redirector for serial devices paused. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_REDIR_PAUSED │ 0x700 │ Redirector paused/active. │
└─────────────────────────────┴───────┴────────────────────────────────────────┘
svcs_code is the error code returned if the designated service stops or fails to start properly. (The exception is a pending service start or stop, where this parameter serves as a bit-map mask providing information about that pending service. A description of this map is included in the pending service start or stop information.) For its primary return codes, the SERVICE.H header file defines high-word values of svcs_code as follows: ┌─────────────────────────────┬───────┬────────────────────────────────────────┐
│ SYMBOLIC CONSTANT │ VALUE │ MEANING │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_NORMAL │ 0 │ Normal. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_BADPARMVAL │ 3051 │ Incorrect parameter value specified. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_MISSPARM │ 3052 │ Missing parameter. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_UNKPARM │ 3053 │ Unknown parameter specified. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_RESOURCE │ 3054 │ Insufficient resource. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_CONFIG │ 3055 │ Configuration faulty. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_SYSTEM │ 3056 │ OS/2 program error. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_INTERNAL │ 3057 │ Internal error encountered. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_AMBIGPARM │ 3058 │ Ambiguous parameter name. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_DUPPARM │ 3059 │ Duplicated parameter. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_KILL │ 3060 │ Ended by the NetServiceControl API. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_EXEC │ 3061 │ Could not run service program file. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_SUBSERV │ 3062│Subservicedidnotstart . │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_CONFLPARM │ 3063 │ Conflict in the value or use of these │
│ │ │ parameters. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_BADCOMPNAME │ 3064 │ Not a valid computer name. │
└─────────────────────────────┴───────┴────────────────────────────────────────┘

The SERVICE.H header file defines low-word values for svcs_code as follows: ┌─────────────────────────────┬───────┬────────────────────────────────────────┐
│ SYMBOLIC CONSTANT │ VALUE │ MEANING │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_M_NULL │ 0 │ Normal. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_M_MEMORY │ 3070 │ Insufficient memory. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_M_DISK │ 3071 │ Insufficient disk space. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_M_THREADS │ 3072 │ Unable to create thread. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_M_PROCESSES │ 3073 │ Unable to create process. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_M_SECURITY │ 3074 │ Security failure. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_M_LANROOT │ 3075 │ Incorrect or missing default path. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_M_REDIR │ 3076 │ Network software not started. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_M_SERVER │ 3077 │ Server software not started. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_M_SEC_FILE_ERR │ 3078 │ Server could not access UAS database. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_M_FILES │ 3079 │ Not supported. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_M_LOGS │ 3080 │ \IBMLAN\LOGS directory not valid. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_M_LANGROUP │ 3081 │ Domain specified could not be used. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_M_MSGNAME │ 3082 │ Computer name is being used as a │
│ │ │ message name on another computer. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_M_ANNOUNCE │ 3083 │ Requester did not announce the server │
│ │ │ name. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_M_UAS │ 3084 │ The UAS database is not configured │
│ │ │ correctly. │
└─────────────────────────────┴───────┴────────────────────────────────────────┘

When the high-word value is SERVICE_UIC_CONFIG (numeric value of 3055), the low-word value can be one of the following: ┌─────────────────────────────┬───────┬────────────────────────────────────────┐
│ SYMBOLIC CONSTANT │ VALUE │ MEANING │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_M_SERVER_SEC_ERR│ 3085 │ Server is not running with user-level │
│ │ │ security. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_M_WKSTA │ 3087 │ The requester detected a problem with │
│ │ │ the cable connection. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_M_ERRLOG │ 3088 │ View your error log (NET.ERR) for │
│ │ │ details. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ SERVICE_UIC_M_LAZY │ 3091 │ The 386 server cannot be started │
│ │ │ because CACHE386.EXE is not running. │
└─────────────────────────────┴───────┴────────────────────────────────────────┘

In the case of a pending service start or stop (SERVICE_INSTALL_PENDING or SERVICE_UNINSTALL_PENDING for the svcs_status field), svcs_code serves as a bit-map mask providing information about that pending service. The SERVICE.H header file defines this bit mask for svcs_code as follows: ┌─────┬────────────────────────┬───────┬───────────────────────────────────────┐
│ BITS│ START PENDING CODE │ BIT │ MEANING │
│ │ │ MASK │ │
├─────┼────────────────────────┼───────┼───────────────────────────────────────┤
│ 0-7 │ SERVICE_CCP_NO_HINT │ 0x0 │ No reason given for start pending. │
│ │ SERVICE_IP_NO_HINT │ │ │
├─────┼────────────────────────┼───────┼───────────────────────────────────────┤
│ 0-7 │ SERVICE_CCP_CHKPT_NUM │ 0xFF │ Checkpoint number incremented each │
│ │ SERVICE_IP_CHKPT_NUM │ │ time the service calls the │
│ │ │ │ NetServiceStatus API (Installer │
│ │ │ │ assumes incrementing denotes a valid │
│ │ │ │ service.) │
├─────┼────────────────────────┼───────┼───────────────────────────────────────┤
│ 8-15│ SERVICE_CCP_WAIT_TIME │ 0xFF00│ Time to wait; expected time (tenths │
│ │ SERVICE_IP_WAIT_TIME │ │ of a second) to start install or to │
│ │ │ │ stop install. │
├─────┼────────────────────────┼───────┼───────────────────────────────────────┤
│ 16 │ SERVICE_CCP_QUERY_HINT │ 0x1000│ Reason given for start or stop │
│ │ SERVICE_IP_QUERY_HINT │ │ pending. │
├─────┼────────────────────────┼───────┼───────────────────────────────────────┤
│ 17-3│ - │ - │ Reserved; must be 0. │
└─────┴────────────────────────┴───────┴───────────────────────────────────────┘
svcs_pid is the process identification number (PID) of a service.
svcs_text is a null reserved ASCII string, unless the service specified by svcs_pid is stopped. In this case, svcs_text must specify a parameter string related to the svcs_code component.

[Back: Service Level 2]
[Next: NetServiceControl or Net32ServiceControl]