feat(mf_getvalue)!: Breaking Change - Improve mf_getvalue()

[tmoody]

Issues

1) Silent misbehaviour.

a) The test for the number of input observations is intended to ensure a selectable row exists but it is performed prior to applying the optional filter which can effectively reduce those rows to zero.

If insufficient observations exist to honour the fetch() call then no feedback or warning is given. The following:

%let myval = %mf_getvalue(<zero obs dataset>,...);

returns an empty value to store in &myval and appears otherwise successful. The empty value could be deemed acceptable if the request was to return a character value. A false positive.

The result of the 'zero obs' example applies also in the case where a filter= argument is supplied that excludes all rows.

In both cases, &SYSCC remains unchanged and the macro fails in an undetectable manner.

b) If a non-existent input data set is named then, although %mf_attrn() logs an ERROR message, processing continues as normal and SYSCC remains unchanged (i.e. still 0 assuming it was 0 before the macro call). This prevents programmatically responding to issues.

2) Restricted to reading the first row of data/filtered data.

This behaviour prevents trivial targeted row access. e.g. from calling %mf_getvalue() from within a loop to access successive rows.

Intent

Change macro to either succeed or report issues and set SYSCC.

1. Because accurately testing the number of observations on a filtered input dataset with attrn()/NLOBSF can be expensive, and NLOBS returns the unfiltered number, the complexity can be reduced by trying only to fulfill the user's request and then test the return code.
   
   The job exit state and log will indicate issues.
   
   Users may add conditional code to test &SYSCC after the macro call for fine-grained program flow if necessary.

2. Permit the user to specify the required observation number, making targeted access possible. e.g.:

%do i = 1 %to %mf_nobs(work.mydata);
  %let this_name = %mf_getvalue(work.mydata,name,fetchobs=&i);
  /* ... use &this_name ... */
%end;

Implementation

• Removal of the mf_getattrn() observation number check.
• Error handling for open() issues. (Previously caught by mf_getattrn())
• Additional fetchobs= macro parameter specifies the desired row of the (optionally filtered) input dataset. Default is 1.
• Changed fetch() to fetchobs() to isolate the requested observation.
• Error/warning handling for unexpected fetchobs() outcomes.

Breaking Change

• With &SYSCC now reflecting WARNINGs and ERRORs occuring during macro execution, previously uncaught issues will result in new behaviour, with SAS potentially returning a non-zero exit code.

Checks

• Code is formatted correctly (sasjs lint).
• Any new functionality has been unit tested.
• All unit tests are passing (sasjs test).
• The PR desc or underlying commits follow the Conventional Commit standard

[allanbowe]

Nice! I don't agree that it's a breaking change - rather, you have caught a previously undetected bug, and now those errors will be rightfully caught, as ought to be expected.

[github-actions]

🎉 This PR is included in version 4.62.1 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀