NON-NUMERIC-JULIAN-THRU date comparison of julian dates was requested and the thru-date is not valid 09 NON-NUMERIC-MDY-THRU date comparison in gregorian was requested and the thru-date is not valid 10 INVALID-MONTH-THRU date comparison was requested and the month of the thru-date is invalid 11 INVALID-DAY-OF-MONTH-THRU date comparison was requested and the day of the thru-month is invalid 12 INVALID-JULIAN-DAY-THRU date comparison was requested and the day number of the julian thru-date is invalid 20 NON-NUMERIC-NBR-DAYS date projection was requested and the number of days is invalid The return code field is redefined as a numeric field (PIC 99) which is named: MAGEC-DATE-RETURN-CODE-N. This enables (cont.) you to use the error codes as a subscript into a table of descriptions if you wish. Be careful not to try to use the (cont.) good return code (blanks) as a subscript, however. The **format specifications** which you can give describe the format of the date you wish to have validated, compared, or projected. In the MAGEC-DATE-FORMAT field enter one of: MMDDYY MM/DD/YY MMDDCCYY MM/DD/CCYY DDMMYY DD/MM/YY DDMMCCYY DD/MM/CCYY YYMMDD YY/MM/DD CCYYMMDD CCYY/MM/DD DDMMMYY DD/MMM/YY DDMMMCCYY DD/MMM/CCYY YYMMMDD YY/MMM/DD CCYYMMMDD CCYY/MMM/DD CCYYDDD CCYY/DDD YYDDD YY/DDD BBBBBBBB (binary date) In the above format specifications you notice that you can specify dates with or without slashes. The format (cont.) specifications which include slashes actually describe a format in which slashes, or dashes, or spaces separate the (cont.) date components. Thus, in a date format of MM/DD/YY a date of 02-21-91 would be accepted as valid The format (cont.) specifications use mnemonic codes, i.e. MM month, 2-digits DD days, 2-digits YY year, 2-digits CCYY century + year, 4-digit year MMM month abbreviation, 3-char. (English) DDD julian day number BBBBBBBB binary date in MAGEC-DATE-FROM-N These same format specifications are used when you request for date conversions or comparisons. In those cases you give a format specification in both MAGEC-DATE-FORMAT and MAGEC-DATE-THRU. The type of operation you request is determined by which of several of the fields within the request area you fill in, (cont.) and which you leave blank (or zero). MAGDATE actually does all possible operations for the given date and fills in all (cont.) of the returned date information regardless of what operation was requested. It is legal for the two input dates, MAGEC-DATE-FROM and MAGEC-DATE-THRU to be in different formats for comparisons or projections. ## Calling MAGDATE You can use MAGDATE to validate a single date in any of the formats supported, to compare two dates of the same or (cont.) different formats, or to project forward or backward a number of days from a given date. The type of operation is (cont.) determined by which portions of the request area you fill in and which portions you leave blank (or zero). MAGDATE (cont.) always sets the return code to indicate successful completion and that your input dates are valid or invalid. It also (cont.) fills in all of the MAGEC-RETURNED-DATE-INFO fields if the return code is blanks (MAGDATE-OK), those fields are filled (cont.) in with zeros if there was an error found in your input date. To do a simple date validation, code: MOVE SPACES TO MAGEC-DATE-REQUEST-AREA. **MOVE subject-date TO MAGEC-DATE-FROM. MOVE date-format TO MAGEC-DATE-FORMAT. CALL 'MAGDATE' USING MAGEC-DATE-REQUEST-AREA. IF (MAGDATE-OK)... In the above example "subject-date" is a dataname of a field containing the date to be validated, "date-format" is the (cont.) dataname of a field containing one of the valid format specifications describing the date being (cont.) edited. To do a date conversion you would code exactly the same as above since MAGDATE always fills in all of the other fields (cont.) in the request area. If MAGDATE-OK is true, you will have the Gregorian, Julian, and alpha-numeric date formats, plus (cont.) the day-of-week, period ending dates, and leap year flag set. A value of "Y" in MAGEC-LEAP-YEAR-CODE indicates that the (cont.) date is in a leap year. To compare two dates to see how many days apart they are, code: MOVE SPACES TO MAGEC-DATE-REQUEST-AREA. MOVE subject-date1 TO MAGEC-DATE-FROM. MOVE subject-date2 TO MAGEC-DATE-THRU. MOVE date-format1 TO MAGEC-DATE-FORMAT. MOVE date-format2 TO MAGEC-DATE-THRU-FORMAT. CALL 'MAGDATE' USING MAGEC-DATE-REQUEST-AREA. IF (MAGDATE-OK)... In the above example "subject-date1" is a dataname of a field containing one date, "subject-date2" is the dataname of a (cont.) field containing another date, "date-format1" is the dataname of a field containing a valid format specification (cont.) describing subject-date1's date, and "date-format2" is the dataname of the field containing subject-date2's date format (cont.) specification. Upon return from MAGDATE, if MAGDATE-OK is true, you will have all of the other fields of the request (cont.) area filled in and the field named MAGEC-PLUS-MINUS-DAYS will contain the number of days between the two dates. If the (cont.) thru-date is earlier than the from-date this value will be negative. *The date information and period ending (cont.) information will apply to the thru-date, not to the from-date.* To do a date projection, code: MOVE SPACES TO MAGEC-DATE-REQUEST-AREA. MOVE subject-date TO MAGEC-DATE-FROM. MOVE date-format1 TO MAGEC-DATE-FORMAT. MOVE date-format2 TO MAGEC-DATE-THRU-FORMAT. MOVE number-of-days TO MAGEC-PLUS-MINUS-DAYS. CALL 'MAGDATE' USING MAGEC-DATE-REQUEST-AREA. IF (MAGDATE-OK)... In the above example "subject-date" is the dataname of a field containing the date you wish to project from, (cont.) "date-format1" is the dataname of a field containing a format specifiction describing the date in subject-date, and (cont.) number-of-days is a numeric value between -99,999 and +99,999. MAGDATE will calculate the date projected either forward (cont.) or backward and place it into MAGEC-DATE-THRU in the format specified in "date-format2". ## Online Demo There is an online demonstration screen which uses MAGDATE. It allows you to enter into the various request area fields (cont.) from your keyboard and to see the results immediately. This can be useful in learning how to use MAGDATE. It can also (cont.) be used to convert or project dates for whatever purpose you might desire. The online MAGDATE demonstration can be invoked using the function code: **DATE No key value is required, you will be able to type into the labelled screen fields which correspond to the request area (cont.) fields. This is a fast way to learn how to use MAGDATE and to see exactly how all of the date information is returned (cont.) from MAGDATE. ## Leap Years In validating and converting dates MAGDATE is cognizant of the fact that leap years are 366 days long and that leap (cont.) years are years which are divisible by four, except that years which are also divisible by one-hundred are not leap (cont.) years unless they are divisible by four-hundred. The year 2000 is a leap year, but the years 1900, 2100, 2200, and 2300 (cont.) are not. *Note: When a 2-digit year format is given with a year of 50 or greater, MAGDATE assumes that the date is a 19xx year; (cont.) if the year is less than 50 it assumes it is a 20xx year.* We strongly recommend clients to *always* use a 4-digit year (cont.) to avoid confusion!** ## Day-of-Week Codes The day-of-week codes in all cases are values from 1 through 7, where 1 = Sunday, 2 = Monday, 7 = Saturday, et cetera. # Appendix P -- Referencing Screen Fields ## Screen Field Names The Mask copybook which MAGEC generates for your screen Mask includes definitions for all your screen fields plus (cont.) definitions for all the necessary control fields associated with them. For each field (assuming a screen field named (cont.) "Sfield") it includes: Sfield the actual screen field SfieldA the 3270 attribute byte SfieldE the field's error flag Sfield-POSN the field's position on the screen For numeric edit-type fields: Sfield-N numeric value of contents of Sfield Sfield-ED Cobol edit pattern for Sfield For date edit-type fields: Sfield-DAY-OF-WEEK Sunday=1, Saturday=7, etc. Sfield-JULIAN-DATE Julian equivalent of entered date For color-controlled fields: Sfield-COLOR color code SfieldH extended highlighting code You can reference any of these control fields in your MMP. Your MMP's automatically have symbolic names defined for all the valid colors and extended highlighting options. They are: Colors: DEFAULT-COLOR   BLUE   RED   PINK   GREEN   TURQUOISE   YELLOW   WHITE   BLACK   Highlighting: NO-HILITE   UNDERLINE   BLINK   REVERSE-VIDEO   ## Symbolic Screen Field References When you are coding customization logic for your MMP's, you will usually be more familiar with the database field (DIT) (cont.) datanames than with the screen field (MSK) datanames. For that reason, you may prefer to utilize MAGEC's **Symbolic (cont.) Screen Field Referencing** feature which is described in detail in the "Database Administration" chapter of the (cont.) "Programmer's Reference Guide. Briefly, it enables you to use the database name to indirectly access screen fields. The mapping of database names to (cont.) screen field names is controlled by the associations defined in the screen's Mask definition. The associations are (cont.) defined using the "Source/Target" specifications for screen fields. Assuming that you had a screen field named SAMOUNT with a source/target named CUS01-AMOUNT, you could code: MOVE +10.00 TO @CUS01-AMOUNT@-N @CUS01-AMOUNT@-ED MOVE RED TO @CUS01-AMOUNT@-COLOR rather than having to look up the screen field name (SAMOUNT) in order to access it. MAGEC will, as the program is being generated, translate the symbolic references into the proper Cobol datanames. You (cont.) can append any of the appropriate suffixes to the symbolic reference, as shown above. Assuming that the screen field (cont.) having CUS01-AMOUNT as its source/target is named SAMOUNT, the above coding would translate into: MOVE +10.00 TO SAMOUNT-N SAMOUNT-ED MOVE RED TO SAMOUNT-COLOR Symbolic references are a good way to access screen fields in routines which are to be stored as copybooks to be (cont.) included into many programs. This way you are not concerned with knowing the datanames used for screen fields in (cont.) Next: https://magec.com/DOC/markdown/cstm16.md.txt