SirFile refresh process

The refresh process checks the usage and growth of file tables, comparing these to threshold values, and it updates the SirFile database.

Two types of refresh

You can request a refresh operation to run once or periodically:

1. A one-time refresh runs in the Model 204 thread of the user requesting the refresh. It can be specified for a single file or for all files that SirFile can access. You invoke a one-time refresh using any of these:
   • The SirFile main menu ADD command, REFRESH command, or the PF12 key
   • The PF12 key on the file tables, system default thresholds, or single file thresholds screen.
   • The SIRFILE BATCH command.

     The SIRFILE BATCH command is usually invoked only in a BATCH204 jobstream, to be run when files are not open for update by any Online. See Running SirFile under BATCH204, below.

2. A periodic refresh, which repeats at a specified time interval, is also called the Background Monitor. This can be invoked by:
   • The PF5 key of the Background File Monitor screen. This runs the refresh on an sdaemon thread, that is, on a different thread from the requesting user.
   • The SIRFILE BACKGROUND interval command. This runs the refresh on an sdaemon thread, and it may be useful in the Online's User 0 stream.
   • The SIRFILE SDAEMON interval command. This runs the refresh on the thread of the requesting user. It is most often invoked by a BATCH2 or IODEV 3 thread.

   Invoking background monitoring, below, further discusses considerations of periodic refreshes.

Whenever the refresh operation is performed, it can consume considerable resources if it calculates the CFULLP (Table C percentage full) value. One of the values specified on the system thresholds screen is whether to allow file-by-file determination of the CFULLP calculation:

• If file-by-file CFULLP determination is allowed, CFULLP is calculated during any type of refresh, for exactly those files that are specified as having the CFULLP calculation performed.
• If CFULLP calculation is not determined on a file-by-file basis, the calculation is performed for all files by the SIRFILE BATCH command, and is not performed by any other type of refresh.

Messages to users and to the audit trail are only sent during a periodic refresh.

The refresh operation details

The refresh process makes a list of all files already in its database, then it adds to the list any files that are currently open in the Online. After this, it runs through the following process for each file on the list:

1. It checks if a file-specific threshold exists. If not, it compares the file to the system default thresholds.
2. If any value in the file exceeds a threshold value, a record is stored for the file, and a warning is posted which causes the file to be highlighted on the SirFile main menu.
3. If the file has not exceeded any thresholds and at least one sample record has been stored for the file, SirFile performs a simple linear regression to predict when the file will fill. If the file-full date falls within the specified number of days of advance warning (as shown on the single file threshold screen), SirFile posts a prediction and a message to the file. The file will now appear highlighted on the main menu and on the file tables screen.
4. If no prediction or warning is posted to the file, SirFile performs a cleanup of any old warnings, predictions, or messages for the file.
5. If the refresh process is running Online, and SirFile encounters a file in its database that it cannot open — because it did not get added to the SIRFILE subsystem definition, or because the file is not allocated to the region — you are prompted for a password.

Invoking background monitoring

SirFile's background monitor runs as a special user in the SIRFILE subsystem to perform a periodic refresh. Messages to users and the audit trail are sent only during a periodic refresh (that is, by the background task).

Any user ID can be the background monitor, and any SirFile user can initiate the background task. The most useful way to run the background monitor is in one of the sdaemon IODEVs set up in the Online. If you are going to run the background file monitor in an sdaemon, you should allocate an extra one explicitly for this task. Failing to allocate an extra sdaemon can slow down other jobs initiated from other products that require sdaemon servicing.

When the background monitoring task is sent to an sdaemon, the task appears as the sdaemon thread number and the user ID of the submitting user. The sdaemon sits in a WAIT state until the specified number of minutes has passed, then it wakes up and runs a SirFile database refresh, sends warnings as appropriate, then returns to a "sleep" state.

You can bump the background task just as you bump any user. To change the time parameter for the background task, it should be bumped and resubmitted.

The PF5 key from the SirFile Background File Monitor screen runs the monitoring task in an sdaemon. You can also use one of the following commands to initiate the task:

Command	Description
SIRFILE BACKGROUND interval	This command, entered at command level or inserted in the User 0 stream, initiates the background task under an sdaemon. interval specifies the number of minutes the background task should sleep between refresh operations. This required value must be between 1 and 1440 (24 hours). If no sdaemon is available or if the background task is already running, the submitting user is warned, and the request is ignored.
SIRFILE SDAEMON interval	This command, entered at command level, causes the session to become the background task. interval specifies the number of minutes the background task should sleep between refresh operations. This required value must be between 1 and 1440 (24 hours). The command may be placed in a BATCH2 or IODEV3 input stream, or it may be typed at command level from any terminal. Typing this command on a terminal will cause that session to become the background SirFile task: that is, it will enter a "sleep" state that is not interruptable unless it is bumped.

Note: You can also use the SIRFILE BATCH command to invoke a single refresh; Running SirFile under BATCH204, below, describes the most useful way to do this.

Running SirFile under BATCH204

Running SirFile's database refresh in batch has two advantages over running it in the Online:

1. It allows the database refresh to be scheduled on a regular basis by a job scheduling system.
2. It allows the most expensive processing in SirFile to be run in off-hours.

In addition, if you have specified N for the following prompt on the system default thresholds screen, the CFULLP statistic is only calculated if the refresh is run via the SIRFILE BATCH command:

Collect CFULLP only on specified files

CFULLP is a more accurate measure of the full status of Table C, but it requires that a TABLEC command be executed, which can be a very resource-intensive operation.

Following is a sample job fragment and CCAIN stream showing the SirFile refresh being run in BATCH204.

//SIRFILE JOB (0) 'Batch Refresh',CLASS=X //REFRESH EXEC PGM=BATCH204,SYSOPT=187 //... //CCASYS DD DSN=M204.CCASYS,DISP=SHR //CCAGRP DD DSN=M204.CCAGRP,DISP=SHR //SIRFILE DD DSN=M204.SIRFILE,DISP=SHR //SIRLOCAL DD DSN=M204.SIRLOCAL,DISP=SHR //PROCFILE DD DSN=M204.PROCFILE,DISP=SHR //PROCFIL2 DD DSN=M204.PROCFIL2,DISP=SHR //... //CCAIN * NFILES=99,NDIRS=99,NDCBS=99,NUSERS=2,NSERVS=2,... IODEV=15,POLLNO=1,NOTERM=1 LOGON filemanagr password OPEN FILE PROCFILE1 password OPEN FILE PROCFIL2 password ... SIRFILE BATCH EOJ /* //

The job is simply a BATCH204 job that contains CCASYS and CCAGRP, and it has a DD card for any file SirFile is going to monitor. The IODEV=15 statement is required; change it to IODEV=nn if you reset the SDAEMDEV parameter to nn. The SYSOPT value for the job must allow for the use of groups and application subsystems. If any file is not yet in the SirFile database or requires a password to open, it should be opened explicitly in the CCAIN stream.

The command SIRFILE BATCH tells the SIRFILE subsystem to run through the refresh process, including TABLEC calculations for CFULLP (Table C percentage full) if CFULLP allocation is not determined file-by-file.

Note: A file must be open with File Manager privileges (PRIVDEF must contain the X'8000' bit) in order for the TABLEC command to operate. When SirFile adds files to its application subsystem definition, it adds them with privileges X'0221' to SCLASS USERS and X'8221' to SCLASS ADMIN. If a site wants to run the batch job with TABLEC commands for each file, the logged-on user in the batch job must be in the ADMIN SCLASS.

Users may customize their run by manually changing privileges for specific files in the USERS SCLASS to X'8221'. Then, running SIRFILE BATCH with a user ID from the USERS SCLASS will only calculate TABLEC for the files with high privileges.

Note: The output will show a failure of the TABLEC command for all files that have privileges that are too low.

See also

• SirFile
• SirFile main menu
• SirFile refresh process
• SirFile single file thresholds
• SirFile Background File Monitor screen‎
• SirFile file tables screen
• SirFile file detail screen
• SirFile messages screen