{ Purpose: To reserve the SPI environment for the user job.
{
{ Format:  Osp$reserve_spi_environment (
{             spi_identifier: ost$spi_identifier;
{             collection_file: amt$local_file_name;
{             number_of_spi_samples: ost$number_of_spi_samples;
{             spi_sampling_interval: ost$spi_sampling_interval;
{             wait: ost$wait;
{             processor_id_set: ost$processor_id_set;
{             data_string: string(32);
{             VAR status: ost$status);
{
{ Parameters:
{
{      Spi_identifier: This parameter specifies the scope for the
{ collection routine. When the program instruction is sampled the
{ SPI identifier is examined. If the value of this parameter is
{ zero then all program samples will be recorded. If the value
{ specified is not zero then only the values equal to the parameter
{ will be recorded. In a multiprocessor system this inspection is
{ done for each processor that has been selected. The following spi
{ identifiers are reserved in the system.
{
{             50 IFEXEC
{             51 RHOUTPUT
{             52 RHINPUT
{             53 MLP$C170_MLI_HELPER
{             54 JMP$JOB_SCHEDULER
{             55 DMP$ADMINISTER_DEVICE_LOG
{             56 DMP$ADMINISTER_ALLOCATION_LOG
{             57 DMP$VOLUME_SPACE_MANAGEMENT
{             58 NAP$INITIALIZE_NETWORKS
{
{      Collection_file: This is the local file name for the file
{ that the SPI collector will write to. The file is opened and processed
{ in a seperate task with the job. The collection is done independently
{ from the rest of the job.
{
{      Number_of_spi_samples: This is the maximum number of SPI samples
{ that you want to collect for each processor. This number is only
{ approximate and will be rounded to the number of samples that
{ will fill full pages.
{
{    Spi_sampling_interval: This parameter specified the amount of time
{ between sampling intervals. The time specified is only an approximation
{ of the time requested. Accurate timing will not occur due to the
{ difference in timing of the processors and the possible interference
{ of system protocol with the processing of SPI data.
{
{     Wait: This parameter specifies if the procedure should wait
{ for the environment to become available. Normallly the environment
{ will not be set. In this case the routine will reserve the
{ environment but in a few cases the environment may already be set
{ by another user. If the value is osc$wait then the procedure will
{ wait for the environment to become available before returning to
{ the user. If on the other hand, the value of the wait parameter is
{ osc$no_wait then control will be return to the user and the
{ value of status will indicate that the environment was not
{ reserved.
{
{      Processor_id_set: This parameter is used to select the
{ processors that SPI will collect P address samples from. The null
{ will return an error code. The cpu does not check if the processor
{ element is on, off, or down. If the element is not on then there
{ will not be any data collection for that element.
{
{      Data_string: This parameter is a 32 charcater string that
{ is used to identify the run. This string is used in all reports
{ as part of the SPI header.
{
{      Status (OUTPUT): This parameter will contain the value of the
{ status for the routine. If normal then the value of status.normal
{ will be set to true else the value of the status.normal will be set
{ to false and the value of status.condition will contain the
{ error code.
{
