@sasjs/utils 2.49.0 → 2.49.2

package/macros/mf_getvarcount.sas

@@ -0,0 +1,49 @@
+/**
+  @file
+  @brief Returns number of variables in a dataset
+  @details Useful to identify those renagade datasets that have no columns!
+  Can also be used to count for numeric, or character columns
+
+      %put Number of Variables=%mf_getvarcount(sashelp.class);
+      %put Character Variables=%mf_getvarcount(sashelp.class,typefilter=C);
+      %put Numeric Variables = %mf_getvarcount(sashelp.class,typefilter=N);
+
+  returns:
+  > Number of Variables=4
+
+
+  @param [in] libds Two part dataset (or view) reference.
+  @param [in] typefilter= (A) Filter for certain types of column.  Valid values:
+    @li A Count All columns
+    @li C Count Character columns only
+    @li N Count Numeric columns only
+
+  @version 9.2
+  @author Allan Bowe
+
+**/
+
+%macro mf_getvarcount(libds,typefilter=A
+)/*/STORE SOURCE*/;
+  %local dsid nvars rc outcnt x;
+  %let dsid=%sysfunc(open(&libds));
+  %let nvars=.;
+  %let outcnt=0;
+  %let typefilter=%upcase(&typefilter);
+  %if &dsid %then %do;
+    %let nvars=%sysfunc(attrn(&dsid,NVARS));
+    %if &typefilter=A %then %let outcnt=&nvars;
+    %else %if &nvars>0 %then %do x=1 %to &nvars;
+      /* increment based on variable type */
+      %if %sysfunc(vartype(&dsid,&x))=&typefilter %then %do;
+        %let outcnt=%eval(&outcnt+1);
+      %end;
+    %end;
+    %let rc=%sysfunc(close(&dsid));
+  %end;
+  %else %do;
+    %put unable to open &libds (rc=&dsid);
+    %let rc=%sysfunc(close(&dsid));
+  %end;
+  &outcnt
+%mend mf_getvarcount;

package/macros/mf_getvarformat.sas

@@ -0,0 +1,72 @@
+/**
+  @file
+  @brief Returns the format of a variable
+  @details Uses varfmt function to identify the format of a particular variable.
+  Usage:
+
+      data test;
+        format str1 $1.  num1 datetime19.;
+        str2='hello mum!'; num2=666;
+        stop;
+      run;
+      %put %mf_getVarFormat(test,str1);
+      %put %mf_getVarFormat(work.test,num1);
+      %put %mf_getVarFormat(test,str2,force=1);
+      %put %mf_getVarFormat(work.test,num2,force=1);
+      %put %mf_getVarFormat(test,renegade);
+
+  returns:
+
+      $1.
+      DATETIME19.
+      $10.
+      8.
+      NOTE: Variable renegade does not exist in test
+
+  @param [in] libds Two part dataset (or view) reference.
+  @param [in] var Variable name for which a format should be returned
+  @param [in] force=(0) Set to 1 to supply a default if the variable has no format
+  @returns outputs format
+
+  @author Allan Bowe
+  @version 9.2
+**/
+
+%macro mf_getVarFormat(libds /* two level ds name */
+      , var /* variable name from which to return the format */
+      , force=0
+)/*/STORE SOURCE*/;
+  %local dsid vnum vformat rc vlen vtype;
+  /* Open dataset */
+  %let dsid = %sysfunc(open(&libds));
+  %if &dsid > 0 %then %do;
+    /* Get variable number */
+    %let vnum = %sysfunc(varnum(&dsid, &var));
+    /* Get variable format */
+    %if(&vnum > 0) %then %let vformat=%sysfunc(varfmt(&dsid, &vnum));
+    %else %do;
+      %put NOTE: Variable &var does not exist in &libds;
+      %let rc = %sysfunc(close(&dsid));
+      %return;
+    %end;
+  %end;
+  %else %do;
+    %put &sysmacroname: dataset &libds not opened! (rc=&dsid);
+    %put &sysmacroname: %sysfunc(sysmsg());
+    %return;
+  %end;
+
+  /* supply a default if no format available */
+  %if %length(&vformat)<2 & &force=1 %then %do;
+    %let vlen = %sysfunc(varlen(&dsid, &vnum));
+    %let vtype = %sysfunc(vartype(&dsid, &vnum.));
+    %if &vtype=C %then %let vformat=$&vlen..;
+    %else %let vformat=best.;
+  %end;
+
+
+  /* Close dataset */
+  %let rc = %sysfunc(close(&dsid));
+  /* Return variable format */
+  &vformat
+%mend mf_getVarFormat;

package/macros/mf_getvarlen.sas

@@ -0,0 +1,56 @@
+/**
+  @file
+  @brief Returns the length of a variable
+  @details Uses varlen function to identify the length of a particular variable.
+  Usage:
+
+      data test;
+        format str $1.  num datetime19.;
+        stop;
+      run;
+      %put %mf_getVarLen(test,str);
+      %put %mf_getVarLen(work.test,num);
+      %put %mf_getVarLen(test,renegade);
+
+  returns:
+
+      1
+      8
+      NOTE: Variable renegade does not exist in test
+
+  @param libds Two part dataset (or view) reference.
+  @param var Variable name for which a length should be returned
+  @returns outputs length
+
+  @author Allan Bowe
+  @version 9.2
+
+**/
+
+%macro mf_getVarLen(libds /* two level ds name */
+      , var /* variable name from which to return the length */
+)/*/STORE SOURCE*/;
+  %local dsid vnum vlen rc;
+  /* Open dataset */
+  %let dsid = %sysfunc(open(&libds));
+  %if &dsid > 0 %then %do;
+    /* Get variable number */
+    %let vnum = %sysfunc(varnum(&dsid, &var));
+    /* Get variable format */
+    %if(&vnum > 0) %then %let vlen = %sysfunc(varlen(&dsid, &vnum));
+    %else %do;
+      %put NOTE: Variable &var does not exist in &libds;
+      %let vlen = %str( );
+    %end;
+  %end;
+  %else %do;
+    %put &sysmacroname: dataset &libds not opened! (rc=&dsid);
+    %put &sysmacroname: %sysfunc(sysmsg());
+    %return;
+  %end;
+
+  /* Close dataset */
+  %let rc = %sysfunc(close(&dsid));
+  /* Return variable format */
+  &vlen
+%mend mf_getVarLen;

package/macros/mf_getvarlist.sas

@@ -0,0 +1,74 @@
+/**
+  @file
+  @brief Returns dataset variable list direct from header
+  @details WAY faster than dictionary tables or sas views, and can
+    also be called in macro logic (is pure macro). Can be used in open code,
+    eg as follows:
+
+        %put List of Variables=%mf_getvarlist(sashelp.class);
+
+  returns:
+  > List of Variables=Name Sex Age Height Weight
+
+  For a seperated list of column values:
+
+        %put %mf_getvarlist(sashelp.class,dlm=%str(,),quote=double);
+
+  returns:
+  > "Name","Sex","Age","Height","Weight"
+
+  @param [in] libds Two part dataset (or view) reference.
+  @param [in] dlm= ( ) Provide a delimiter (eg comma or space) to separate the
+    variables
+  @param [in] quote= (none) use either DOUBLE or SINGLE to quote the results
+  @param [in] typefilter= (A) Filter for certain types of column.  Valid values:
+    @li A Return All columns
+    @li C Return Character columns
+    @li N Return Numeric columns
+
+  @version 9.2
+  @author Allan Bowe
+
+**/
+
+%macro mf_getvarlist(libds
+      ,dlm=%str( )
+      ,quote=no
+      ,typefilter=A
+)/*/STORE SOURCE*/;
+  /* declare local vars */
+  %local outvar dsid nvars x rc dlm q var vtype;
+
+  /* credit Rowland Hale  - byte34 is double quote, 39 is single quote */
+  %if %upcase(&quote)=DOUBLE %then %let q=%qsysfunc(byte(34));
+  %else %if %upcase(&quote)=SINGLE %then %let q=%qsysfunc(byte(39));
+  /* open dataset in macro */
+  %let dsid=%sysfunc(open(&libds));
+
+  %if &dsid %then %do;
+    %let nvars=%sysfunc(attrn(&dsid,NVARS));
+    %if &nvars>0 %then %do;
+      /* add variables with supplied delimeter */
+      %do x=1 %to &nvars;
+        /* get variable type */
+        %let vtype=%sysfunc(vartype(&dsid,&x));
+        %if &vtype=&typefilter or &typefilter=A %then %do;
+          %let var=&q.%sysfunc(varname(&dsid,&x))&q.;
+          %if &var=&q&q %then %do;
+            %put &sysmacroname: Empty column found in &libds!;
+            %let var=&q. &q.;
+          %end;
+          %if %quote(&outvar)=%quote() %then %let outvar=&var;
+          %else %let outvar=&outvar.&dlm.&var.;
+        %end;
+      %end;
+    %end;
+    %let rc=%sysfunc(close(&dsid));
+  %end;
+  %else %do;
+    %put &sysmacroname: Unable to open &libds (rc=&dsid);
+    %put &sysmacroname: SYSMSG= %sysfunc(sysmsg());
+    %let rc=%sysfunc(close(&dsid));
+  %end;
+  %do;%unquote(&outvar)%end;
+%mend mf_getvarlist;

package/macros/mf_getvarnum.sas

@@ -0,0 +1,58 @@
+/**
+  @file
+  @brief Returns the position of a variable in dataset (varnum attribute).
+  @details Uses varnum function to determine position.
+
+Usage:
+
+    data work.test;
+      format str $1.  num datetime19.;
+      stop;
+    run;
+    %put %mf_getVarNum(work.test,str);
+    %put %mf_getVarNum(work.test,num);
+    %put %mf_getVarNum(work.test,renegade);
+
+returns:
+
+  > 1
+
+  > 2
+
+  > NOTE: Variable renegade does not exist in test
+
+  @param libds Two part dataset (or view) reference.
+  @param var Variable name for which a position should be returned
+
+  @author Allan Bowe
+  @version 9.2
+
+**/
+
+%macro mf_getVarNum(libds /* two level ds name */
+      , var /* variable name from which to return the format */
+)/*/STORE SOURCE*/;
+  %local dsid vnum rc;
+  /* Open dataset */
+  %let dsid = %sysfunc(open(&libds));
+  %if &dsid > 0 %then %do;
+    /* Get variable number */
+    %let vnum = %sysfunc(varnum(&dsid, &var));
+    %if(&vnum <= 0) %then %do;
+      %put NOTE: Variable &var does not exist in &libds;
+      %let vnum = %str( );
+    %end;
+  %end;
+  %else %do;
+    %put &sysmacroname: dataset &libds not opened! (rc=&dsid);
+    %put &sysmacroname: %sysfunc(sysmsg());
+    %return;
+  %end;
+
+  /* Close dataset */
+  %let rc = %sysfunc(close(&dsid));
+
+  /* Return variable number */
+    &vnum.
+
+%mend mf_getVarNum;

package/macros/mf_getvartype.sas

@@ -0,0 +1,52 @@
+/**
+  @file
+  @brief Returns variable type - Character (C) or Numeric (N)
+  @details
+Usage:
+
+      data test;
+        length str $1.  num 8.;
+        stop;
+      run;
+      %put %mf_getvartype(test,str);
+      %put %mf_getvartype(work.test,num);
+
+
+
+  @param libds Two part dataset (or view) reference.
+  @param var the variable name to be checked
+  @return output returns C or N depending on variable type.  If variable
+    does not exist then a blank is returned and a note is written to the log.
+
+  @version 9.2
+  @author Allan Bowe
+
+**/
+
+%macro mf_getvartype(libds /* two level name */
+      , var /* variable name from which to return the type */
+)/*/STORE SOURCE*/;
+  %local dsid vnum vtype rc;
+  /* Open dataset */
+  %let dsid = %sysfunc(open(&libds));
+  %if &dsid. > 0 %then %do;
+    /* Get variable number */
+    %let vnum = %sysfunc(varnum(&dsid, &var));
+    /* Get variable type (C/N) */
+    %if(&vnum. > 0) %then %let vtype = %sysfunc(vartype(&dsid, &vnum.));
+    %else %do;
+      %put NOTE: Variable &var does not exist in &libds;
+      %let vtype = %str( );
+    %end;
+  %end;
+  %else %do;
+    %put &sysmacroname: dataset &libds not opened! (rc=&dsid);
+    %put &sysmacroname: %sysfunc(sysmsg());
+    %return;
+  %end;
+
+  /* Close dataset */
+  %let rc = %sysfunc(close(&dsid));
+  /* Return variable type */
+  &vtype
+%mend mf_getvartype;

package/macros/mf_getxengine.sas

@@ -0,0 +1,43 @@
+/**
+  @file
+  @brief Returns the engine type of a SAS fileref
+  @details Queries sashelp.vextfl to get the xengine value.
+  Usage:
+
+      filename feng temp;
+      %put %mf_getxengine(feng);
+
+  returns:
+  > TEMP
+
+  @param fref The fileref to check
+
+  @returns The XENGINE value in sashelp.vextfl or 0 if not found.
+
+  @version 9.2
+  @author Allan Bowe
+
+  <h4> Related Macros </h4>
+  @li mf_getengine.sas
+
+**/
+
+%macro mf_getxengine(fref
+)/*/STORE SOURCE*/;
+  %local dsid engnum rc engine;
+
+  %let dsid=%sysfunc(
+    open(sashelp.vextfl(where=(fileref="%upcase(&fref)")),i)
+  );
+  %if (&dsid ^= 0) %then %do;
+    %let engnum=%sysfunc(varnum(&dsid,XENGINE));
+    %let rc=%sysfunc(fetch(&dsid));
+    %let engine=%sysfunc(getvarc(&dsid,&engnum));
+    %* put &fref. ENGINE is &engine.;
+    %let rc= %sysfunc(close(&dsid));
+  %end;
+  %else %let engine=0;
+
+  &engine
+
+%mend mf_getxengine;

package/macros/mf_increment.sas

@@ -0,0 +1,29 @@
+/**
+  @file
+  @brief Increments a macro variable
+  @details Useful outside of do-loops - will increment a macro variable every
+  time it is called.
+
+  Example:
+
+      %let cnt=1;
+      %put We have run %mf_increment(cnt) lines;
+      %put Now we have run %mf_increment(cnt) lines;
+      %put There are %mf_increment(cnt) lines in total;
+
+  @param [in] MACRO_NAME the name of the macro variable to increment
+  @param [in] ITER= The amount to add or subtract to the macro
+
+  <h4> Related Files </h4>
+  @li mf_increment.test.sas
+
+**/
+
+%macro mf_increment(macro_name,incr=1);
+
+  /* iterate the value */
+  %let &macro_name=%eval(&&&macro_name+&incr);
+  /* return the value */
+  &&&macro_name
+
+%mend mf_increment;

package/macros/mf_isblank.sas

@@ -0,0 +1,27 @@
+/**
+  @file mf_isblank.sas
+  @brief Checks whether a macro variable is empty (blank)
+  @details Simply performs:
+
+      %sysevalf(%superq(param)=,boolean)
+
+  Usage:
+
+      %put mf_isblank(&var);
+
+  inspiration:
+  https://support.sas.com/resources/papers/proceedings09/022-2009.pdf
+
+  @param param VALUE to be checked
+
+  @return output returns 1 (if blank) else 0
+
+  @version 9.2
+**/
+
+%macro mf_isblank(param
+)/*/STORE SOURCE*/;
+
+  %sysevalf(%superq(param)=,boolean)
+
+%mend mf_isblank;

package/macros/mf_isdir.sas

@@ -0,0 +1,34 @@
+/**
+  @file
+  @brief Checks whether a path is a valid directory
+  @details
+  Usage:
+
+      %let isdir=%mf_isdir(/tmp);
+
+  With thanks and full credit to Andrea Defronzo -
+  https://www.linkedin.com/in/andrea-defronzo-b1a47460/
+
+  @param path full path of the file/directory to be checked
+
+  @return output returns 1 if path is a directory, 0 if it is not
+
+  @version 9.2
+**/
+
+%macro mf_isdir(path
+)/*/STORE SOURCE*/;
+  %local rc did is_directory fref_t;
+
+  %let is_directory = 0;
+  %let rc = %sysfunc(filename(fref_t, %superq(path)));
+  %let did = %sysfunc(dopen(&fref_t.));
+  %if &did. ^= 0 %then %do;
+    %let is_directory = 1;
+    %let rc = %sysfunc(dclose(&did.));
+  %end;
+  %let rc = %sysfunc(filename(fref_t));
+
+  &is_directory
+
+%mend mf_isdir;

package/macros/mf_isint.sas

@@ -0,0 +1,36 @@
+/**
+  @file
+  @brief Returns 1 if the variable contains only digits 0-9, else 0
+  @details Note that numerics containing any punctuation (including decimals
+    or exponents) will be flagged zero.
+
+  If you'd like support for this, then do raise an issue (or even better, a
+  pull request!)
+
+  Usage:
+
+      %put %mf_isint(1) returns 1;
+      %put %mf_isint(1.1) returns 0;
+      %put %mf_isint(%str(1,1)) returns 0;
+
+  @param [in] arg input value to check
+
+  @version 9.2
+**/
+
+%macro mf_isint(arg
+)/*/STORE SOURCE*/;
+
+  /* blank val is not an integer */
+  %if "&arg"="" %then %do;0%return;%end;
+
+  /* remove minus sign if exists */
+  %local val;
+  %if "%substr(%str(&arg),1,1)"="-" %then %let val=%substr(%str(&arg),2);
+  %else %let val=&arg;
+
+  /* check remaining chars */
+  %if %sysfunc(findc(%str(&val),,kd)) %then %do;0%end;
+  %else %do;1%end;
+
+%mend mf_isint;

package/macros/mf_islibds.sas

@@ -0,0 +1,40 @@
+/**
+  @file
+  @brief Checks whether a string follows correct library.dataset format
+  @details Many macros in the core library accept a library.dataset parameter
+  referred to as 'libds'.  This macro validates the structure of that parameter,
+  eg:
+
+    @li 8 character libref?
+    @li 32 character dataset?
+    @li contains a period?
+
+  It does NOT check whether the dataset exists, or if the library is assigned.
+
+  Usage:
+
+      %put %mf_islibds(work.something)=1;
+      %put %mf_islibds(nolib)=0;
+      %put %mf_islibds(badlibref.ds)=0;
+      %put %mf_islibds(w.t.f)=0;
+
+  @param [in] libds The string to be checked
+
+  @return output Returns 1 if libds is valid, 0 if it is not
+
+  <h4> Related Macros </h4>
+  @li mf_islibds.test.sas
+  @li mp_validatecol.sas
+
+  @version 9.2
+**/
+
+%macro mf_islibds(libds
+)/*/STORE SOURCE*/;
+
+%local regex;
+%let regex=%sysfunc(prxparse(%str(/^[_a-z]\w{0,7}\.[_a-z]\w{0,31}$/i)));
+
+%sysfunc(prxmatch(&regex,&libds))
+
+%mend mf_islibds;

package/macros/mf_loc.sas

@@ -0,0 +1,29 @@
+/**
+  @file
+  @brief Returns physical location of various SAS items
+  @details Returns location of the PlatformObjectFramework tools
+    Usage:
+
+      %put %mf_loc(POF); %*location of PlatformObjectFramework tools;
+
+  @version 9.2
+  @author Allan Bowe
+**/
+
+%macro mf_loc(loc);
+%let loc=%upcase(&loc);
+%local root;
+
+%if &loc=POF or &loc=PLATFORMOBJECTFRAMEWORK %then %do;
+  %let root=%substr(%sysget(SASROOT),1,%index(%sysget(SASROOT),SASFoundation)-2);
+  %let root=&root/SASPlatformObjectFramework/&sysver;
+  %put Batch tools located at: &root;
+  &root
+%end;
+%else %if &loc=VIYACONFIG %then %do;
+  %let root=/opt/sas/viya/config;
+  %put Viya Config located at: &root;
+  &root
+%end;
+
+%mend mf_loc;

package/macros/mf_mkdir.sas

@@ -0,0 +1,67 @@
+/**
+  @file
+  @brief Creates a directory, including any intermediate directories
+  @details Works on windows and unix environments via dcreate function.
+Usage:
+
+    %mf_mkdir(/some/path/name)
+
+
+  @param dir relative or absolute pathname.  Unquoted.
+  @version 9.2
+
+**/
+
+%macro mf_mkdir(dir
+)/*/STORE SOURCE*/;
+
+  %local lastchar child parent;
+
+  %let lastchar = %substr(&dir, %length(&dir));
+  %if (%bquote(&lastchar) eq %str(:)) %then %do;
+    /* Cannot create drive mappings */
+    %return;
+  %end;
+
+  %if (%bquote(&lastchar)=%str(/)) or (%bquote(&lastchar)=%str(\)) %then %do;
+    /* last char is a slash */
+    %if (%length(&dir) eq 1) %then %do;
+      /* one single slash - root location is assumed to exist */
+      %return;
+    %end;
+    %else %do;
+      /* strip last slash */
+      %let dir = %substr(&dir, 1, %length(&dir)-1);
+    %end;
+  %end;
+
+  %if (%sysfunc(fileexist(%bquote(&dir))) = 0) %then %do;
+    /* directory does not exist so prepare to create */
+    /* first get the childmost directory */
+    %let child = %scan(&dir, -1, %str(/\:));
+
+    /*
+      If child name = path name then there are no parents to create. Else
+      they must be recursively scanned.
+    */
+
+    %if (%length(&dir) gt %length(&child)) %then %do;
+      %let parent = %substr(&dir, 1, %length(&dir)-%length(&child));
+      %mf_mkdir(&parent)
+    %end;
+
+    /*
+      Now create the directory.  Complain loudly of any errs.
+    */
+
+    %let dname = %sysfunc(dcreate(&child, &parent));
+    %if (%bquote(&dname) eq ) %then %do;
+      %put %str(ERR)OR: could not create &parent + &child;
+      %abort cancel;
+    %end;
+    %else %do;
+      %put Directory created:  &dir;
+    %end;
+  %end;
+  /* exit quietly if directory did exist.*/
+%mend mf_mkdir;

package/macros/mf_mval.sas

@@ -0,0 +1,19 @@
+/**
+  @file mf_mval.sas
+  @brief Returns a macro variable value if the variable exists
+  @details
+  Use this macro to avoid repetitive use of `%if %symexist(MACVAR) %then`
+  type logic.
+  Usage:
+
+      %if %mf_mval(maynotexist)=itdid %then %do;
+
+  @version 9.2
+  @author Allan Bowe
+**/
+
+%macro mf_mval(var);
+  %if %symexist(&var) %then %do;
+    %superq(&var)
+  %end;
+%mend mf_mval;