This section describes how Run Command On Workstation jobs are transmitted from the site database to SMS logon servers and clients. This process is summarized in Figure 3.10, Run Command On Workstation Software Distribution.
A Run Command On Workstation job runs a command defined for a package at specified clients. You can use a Run Command On Workstation job to install a package or to run a command on individual clients.
To install a package on clients, you create a package with Workstations properties, and then create a Run Command On Workstation job for that package. After the job is created, it is added to the site database where the Scheduler monitors all jobs created at the site.
The Scheduler has a polling interval for checking jobs in the SMS database. This polling interval is based on the Response setting in the Services dialog box within Site Properties. This means that if the Scheduler is in the inactive state of a polling interval, it may not detect all new jobs or active jobs (or any changes to a job) at the moment that their Start After times elapse—the Scheduler will detect and process the new, active, or changed jobs when the current polling interval elapses, at which time it will check the jobs in the SMS database.
After the job's Start After time elapses, the Scheduler starts the job by creating a compressed package file (packageid.W* where packageid is the eight character package ID for the package used by the job) that contains all subdirectories and files within the package's source directory. The packageid.W* file is placed in the SITE.SRV\SENDER.BOX\TOSEND directory of the SMS root directory.
The Scheduler then creates a despooler instruction file for each target site. A despooler instruction file contains instructions for completing the job at each target site (instructionid.I* where instructionid is the five character unique ID in the job ID followed by the site code for the target site). The instructionid.I* file is placed in the SITE.SRV\SENDER.BOX\TOSEND directory.
Figure 3.10 Run Command On Workstation Software Distribution
For each target site specified for the job, the Scheduler also creates a send request file. A send request file (*.SRQ) contains instructions for sending the compressed package and the despooler instruction file to the target site. Initially, the *.SRQ file is placed in the appropriate outbox directory (SITE.SRV\SENDER.BOX \REQUESTS\sender.000 where sender.000 is the specific sender's outbox directory name, such as LAN_DEFA.000, SNA_BATC.000, or RAS_ISDN.000) for the type of sender being used to send the job to the target site. For example, if a package is sent to the target site using the LAN Sender, the SRQ file would be placed in the LAN_DEFA.000 directory of the REQUESTS directory.
You can check these directories to verify that the Scheduler has processed the job properly.
Note
If you have created a job with the current site as the target, SMS uses the same method for transmitting the package and instructions as a job targeted to child sites. When you install a primary site, a LAN Sender is automatically installed and a LAN Sender address is also automatically created for the site itself. This address is used for the sending process for jobs created at the current site and targeted at the site itself. You should never delete this address.
The sender monitors its outbox for a valid send request. When it detects a new send request, it renames it to *.SRS to indicate the send is in progress.
The sender connects to the target site and transfers the compressed package file and the despooler instruction file from the SITE.SRV\SENDER.BOX\TOSEND directory on the site server to the SITE.SRV\DESPOOLR.BOX\RECEIVE directory on the target site server. The Despooler renames the compressed package to *.PCK. This directory can be monitored at the site server to check the sender's progress.
After the *.PCK file reaches its full size at the parent site, the sender transfers the instruction file as a .TMP file. When the instruction file transfer is complete, it is renamed as a valid instruction file (*.INS). You can verify the compressed package and its instruction file were properly sent to the target site by checking the SITE.SRV\DESPOOLR.BOX\RECEIVE directory on the destination site server.
At the site server for the target site, the Despooler monitors the SITE.SRV \DESPOOLR.BOX\RECEIVE directory for instruction files and then processes the files. The Despooler moves the compressed package to the SITE.SRV \DESPOOLR.BOX\STORE directory. Packages for Run Command On Workstation jobs are saved as packageID.WKS.
Next, the Despooler at the target site decompresses the compressed package (.WKS file) into the package source directory's original files and directory structure. The Despooler decompresses the package directory into a temporary directory located at the root directory of the local drive with the most free space.
Note that if the package contains NTFS-format files (such as Macintosh files or files with a long file name or unique characters), the Despooler uses the local NTFS drive with the most free space for its temporary directory.
Note that a preferred drive can be set in the following registry key: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SMS\Components\SMS_DESPOOLER\Preferred Drive For Temp Directory.
The Despooler copies the decompressed package directory and files from the temporary directory to the target distribution servers specified by the job. Where the package directory is then placed on each target distribution server depends on the type of server:
If SMS_PKGx has not already been created, the Despooler determines the drive that contains the SMS_SHR share. If this share has at least 100 MB of free space, it is used. If there is less than 100 MB free, the Despooler uses the NTFS drive with the most available free space. If no NTFS drive has at least 100 MB free, it uses the non-NTFS drive with the most available free space. If no other drives have 100 MB free, the drive containing the SMS_SHR is used. Note that the minimum free space requirement is 100 MB by default; however, it can be set in the following registry key:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SMS\Components\SMS_DESPOOLER\SMS Drive Minimum Free Space in Mbytes
The only exception to this is if the SMS root directory is on a drive formatted as FAT and the package requires NTFS (such as a Macintosh package or a package source directory that contains NTFS long names). In this case, the Despooler searches for a drive formatted as NTFS. If it finds an NTFS drive, the Despooler creates the SMS_PKGx directory at the root of that drive (where x is the drive letter), shares the directory as SMS_PKGx, creates a subdirectory (beneath that directory) with the same name as the package ID, and installs the package in this subdirectory. If no NTFS drive is found, the Despooler retries up to 100 times, waiting the amount of time specified by its set interval between each retry.
After the Despooler copies the decompressed package from the temporary directory to all the target distribution servers, the Despooler deletes the temporary directory and its contents. The Maintenance Manager creates a Package Location MIF file (*.PMF) that is reported back to the sending site. This information is written to the database. It indicates where the package has been installed. When you do Remove Package From Server jobs, the package can only be removed from servers reported in a Package Location MIF file.
For a Run Command On Workstation job, the Despooler uses the job's despooler instruction file to create a PCM instruction file for each target client in the target site's domains. PCM instruction files contain package installation instructions for individual clients. For each domain in the site, there is a domain master box where PCM instruction files for the domain are placed. The domain master box directory is SITE.SRV\MAINCFG.BOX\PCMDOM.BOX\domain_name.000. For each target client, a PCM instruction file for the target client is placed on all SMS logon servers in the SMS domain containing that client.
You can verify the PCM instruction files (workstation_unique_ID.INS) were created by checking the SITE.SRV\MAINCFG.BOX\PCMDOM.BOX \domain_name.000 directories on the site server.
Maintenance Manager replicates the PCM instruction files from the SITE.SRV\MAINCFG.BOX\PCMDOM.BOX\domain_name.000 directories on the site server to the LOGON.SRV\PCMINS.BOX directory on all the SMS logon servers in the target domains. The PCM instruction file is named according to the client's SMS ID (for example, D9500002.INS).
At the SMS client, Package Command Manager monitors the LOGON.SRV \PCMINS.BOX directory of the client's SMS logon server for new PCM instruction files. A package appears in the Package Command Manager window when the client's time is later than the Offer After time set for the job. To run the package command, the user at the client selects the package and chooses the Run button. The Package Command Manager runs the package's command.
Note
There are four possible extensions for an instruction file (*.INS, *.SNI, *.IST, and *.NIL). There are four possible file names for a package (*.PCK, *.PKG, packageid.SRV, and packageid.WKS).
SMS components only create instructions as *.SNI or *.INS. The *.INS files contain compressed instructions and the *.SNI files hold decompressed instructions. An *.INS or *.SNI instruction becomes *.IST or *.NIL when the Despooler starts processing the instruction. A *.IST file is for instructions which have an accompanying package file. A *.NIL file is for standalone instructions.
The *.PCK files become *.PKG files the moment their respective *.INS or *.SNI files become *.IST files. When the Despooler at the receiving site moves a compressed *.PKG file into the SITE.SRV\DESPOOLR.BOX\STORE directory, it renames it to packageID.WKS (for client packages) or packageID.SRV.
After the Package Command Manager completes a package installation (that is, it has run the package command), it creates a despooler instruction file that reports status for the Run Command On Workstation job. The Package Command Manager places the file in the DESPOOLR.BOX directory specified by the ResultsSharePoint entry in the client's SMS.INI file. If the SMS logon server is a NetWare server, the file is placed on the volume containing the SMS installation directory on the server. If the package installation script calls the ISVMIF DLL to report status or writes a text status MIF file to the Windows directory, the Package Command Manager puts this file in the DESPOOLR.BOX as a *.MIF file.
After running a package, the Package Command Manager also modifies the PCMHIST.REG file to indicate the package was run. The PCMHIST.REG file is located in the MS\SMS\DATA directory on the client. All information about whether a command has been run, has been archived, or is pending is stored in this file.
The Maintenance Manager monitors the DESPOOLR.BOX on all SMS logon servers and moves files back to the SITE.SVR\DESPOOLR.BOX\RECEIVE directory on the site server. The Despooler reads the instruction file and processes the instruction. It also updates the master copy of the PCM instruction file in the DOMAINMASTERINBOX directory (SITE.SRV\MAINCFG.BOX \PCMDOM.BOX\domain.name.000). The Maintenance Manager copies this file to the LOGON.SRV\PCMINS.BOX directory on all SMS logon servers in the SMS domain containing the client.
The Despooler then creates a job status MIF file which reports the package installation status from the client back to the site where the job was created. The job status MIF file has an extension of .JMF. This .JMF file is sent up the hierarchy just like an event MIF file, inventory MIF file, or other MIF file. Note that job status MIF files in SMS 1.0 had an extension of .MIF. For primary sites, the .JMF file is placed in the SITE.SRV\DATALOAD.BOX\DELTAMIF.COL directory. For secondary sites, the .JMF file is placed directly in the SITE.SRV \SITEREP.BOX directory. If the package command reports a failed status, the Despooler logs an event to the Windows NT event log on the site server and writes an error event MIF file (event MIF files have an extension of .EMF) to the SITE.SRV\DATALOAD.BOX\DELTAMIF.COL directory on the site server. If the package command created a text status MIF file, the description attribute is included in this event. For information about how events are reported, see "Event Processing" later in this chapter.
If the current site is the originating site for the job, the Inventory Data Loader reads the .JMF file and uses it to update the job's status in the site database. The Inventory Data Loader is a multi-threaded process (new for SMS 1.2). The main thread of the Inventory Data Loader takes the MIF files in the SITE.SRV \DATALOAD.BOX\DELTAMIF.COL directory and places them into the PROCESS subdirectory. If the Inventory Data Loader does not have an active thread for processing .JMF files, it will spawn a .JMF processing thread. Note that the Inventory Data Loader can have a separate thread to process the five types of MIF files, which are distinguished by their file extensions. Also note that the main thread limits the number of MIF files of each type to 1000 files—when the count falls below 1000 for a type of MIF file, the main thread moves more MIF files of that type to the PROCESS subdirectory. The .JMF processing thread updates the site database with job status reported by the clients. Note that the thread performs a syntax check on the .JMF file and places these files in the BADMIFS subdirectory if the MIF file cannot be processed. If there are no more MIF files to process, the thread terminates.
If the current site is a primary site that is not the originating site for the job, the Inventory Data Loader moves the .JMF file to the SITE.SRV\SITEREP.BOX directory. If the current site is a secondary site, the Despooler places the .JMF directly in the SITE.SRV\SITEREP.BOX directory (and never in the SITE.SRV \DATALOAD.BOX\DELTAMIF.COL directory).
When the Site Reporter detects a queue of MIF files, it creates a system job that sends the MIF files to the current site's parent site. The trigger queue length is determined by Service Response settings in the Site Properties dialog box.
The system job's instruction file is placed in the SITE.SRV\SCHEDULE.BOX directory. The Scheduler monitors this directory for system job instructions. For each system job, the Scheduler creates a despooler instruction file (jobid.I* where jobid is the eight character job ID for the job) and compresses the MIF files into a single file (jobid.P*). These files are placed in the SITE.SRV\SENDER.BOX \TOSEND directory.
The Scheduler then creates a send request file (*.SRQ) in the appropriate sender's outbox directory. The sender processes the request and transfers the data to the parent site. At the parent site, the Despooler reads the instruction file and carries out its instructions by decompressing the compressed file containing the MIF files in the SITE.SRV\DATALOAD.BOX\DELTAMIF.COL directory on the site server.
If the parent site is not the originating site for the job, the Inventory Data Loader moves the .JMF file to the SITE.SRV\SITEREP.BOX directory and forwards it to its parent site, and so on until it reaches the originating site.
If the parent site is the originating site for the job, the Inventory Data Loader reads the .JMF file, moves it to the SITE.SRV\DATALOAD.BOX\DELTAMIF.COL \PROCESS directory, and uses it to update the job's status in the site database.
To view job status reported by Package Command Manager, open the Job Properties dialog box for the job, choose the Status button, select the site for which you want to view status, and choose the Details button. The job's status at each client and distribution server is displayed in the list box.
A package command can write a MIF file to the Windows directory to provide more detailed status. This status MIF file is called a package command status MIF file. A program started by a package command can also call a function from the ISVMIF DLL to report status on the job that corresponds to the package command. For more information on reporting status with the ISVMIF DLL, see the Microsoft BackOffice Development Kit. For information about the package command status MIF file format, see Chapter 4, "File Formats."
If a program writes a MIF file to the Windows directory, Package Command Manager collects the file and places it (and the despooler instruction file) in the DESPOOLR.BOX directory specified by the ResultsSharePoint entry in the client's SMS.INI file. Note that the date and time on the MIF file must be later than the date and time specified for the job start time (or Package Command Manager will not collect the file).
The package command status MIF file has priority over the despooler instruction file. This means that the Despooler uses the status reported in the package command status MIF file to create a job status MIF file (*.JMF). The job status MIF file reports the job status up the hierarchy to the site where the job was created. If a failure occurs, the job status MIF file includes a text description of the failure reported by the package command status MIF file, and the Despooler logs an event in the Windows NT event log on the site server using this description.
A package command status MIF file includes one group (InstallStatus) that contains two attributes (Status and Description).
The Status attribute determines the status reported back to the originating site. This status is included in the job details status MIF file that the Despooler writes and that eventually makes its way back to the originating site's job details data for this job in the database.
The Description attribute is used only if the Status is FAILED—in which case, the Description is used as text in an SMS event and a Windows NT event. If the MIF file contains a FAILED status and includes a description string, the string is reported by the Despooler in a Windows NT event to the computer's site server Windows NT event log and is reported as an SMS event, which also eventually makes its way back up the site hierarchy to the originating site's database. If the MIF file contains a SUCCESS status, the description string is not reported back.
In the SMS Administrator, you can view the status in the Job Status Details dialog box for the job. If the package command reports a FAILED status, you can view the generated event in the Events window in the SMS Administrator.